@olenbetong/synergi-react 5.5.0 → 5.6.0
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.
- package/es/chrome/assistant.d.ts +75 -0
- package/es/chrome/assistant.js +116 -0
- package/es/index.d.ts +1 -0
- package/es/index.js +1 -0
- package/package.json +1 -1
- package/src/chrome/assistant.test.tsx +106 -0
- package/src/chrome/assistant.ts +178 -0
- package/src/index.ts +9 -0
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
/** A JSON Schema object describing a tool's arguments. */
|
|
2
|
+
export type AssistantToolParameters = {
|
|
3
|
+
type: "object";
|
|
4
|
+
properties?: Record<string, unknown>;
|
|
5
|
+
required?: string[];
|
|
6
|
+
[key: string]: unknown;
|
|
7
|
+
};
|
|
8
|
+
/**
|
|
9
|
+
* A tool the app offers the assistant. The handler runs in the page with the user's own
|
|
10
|
+
* permissions; what it returns (JSON-serialisable) is what the model sees.
|
|
11
|
+
*/
|
|
12
|
+
export type AssistantTool<TArgs = Record<string, unknown>> = {
|
|
13
|
+
/** Letters, digits, `_` and `-`, at most 64 characters; unique on the page. */
|
|
14
|
+
name: string;
|
|
15
|
+
/** What the tool does and when to use it. The model reads this to decide. */
|
|
16
|
+
description: string;
|
|
17
|
+
/**
|
|
18
|
+
* A few words for the user, shown in the panel when the tool has run ("Read the open document"),
|
|
19
|
+
* in their language. Never sent to the model. Without it the panel shows the name.
|
|
20
|
+
*/
|
|
21
|
+
label?: string;
|
|
22
|
+
/** The arguments, as a JSON Schema object. Leave out for a tool without arguments. */
|
|
23
|
+
parameters?: AssistantToolParameters;
|
|
24
|
+
handler: (args: TArgs) => unknown | Promise<unknown>;
|
|
25
|
+
/**
|
|
26
|
+
* Ask the user before running: `true` for a generic question, or a function returning the
|
|
27
|
+
* question for these arguments. Use it for every tool that changes something.
|
|
28
|
+
*/
|
|
29
|
+
confirm?: boolean | ((args: TArgs) => string);
|
|
30
|
+
};
|
|
31
|
+
type AssistantApi = {
|
|
32
|
+
readonly enabled: boolean;
|
|
33
|
+
registerTool: (tool: AssistantTool<any>) => () => void;
|
|
34
|
+
setInstructions?: (instructions: string | null) => void;
|
|
35
|
+
setContext: (context: unknown) => void;
|
|
36
|
+
open: () => void;
|
|
37
|
+
close: () => void;
|
|
38
|
+
};
|
|
39
|
+
/**
|
|
40
|
+
* Calls `use` with the assistant once the chrome is on the page - at once when it already is -
|
|
41
|
+
* and returns a function that undoes it (or stops waiting). Skipped when the assistant is off.
|
|
42
|
+
*/
|
|
43
|
+
export declare function withAssistant(use: (assistant: AssistantApi) => void | (() => void)): () => void;
|
|
44
|
+
/** Whether the assistant is enabled on this page (the chrome is mounted and the feature is on). */
|
|
45
|
+
export declare function isAssistantEnabled(): boolean;
|
|
46
|
+
/** Opens the assistant panel, when the assistant is enabled. */
|
|
47
|
+
export declare function openAssistant(): void;
|
|
48
|
+
/**
|
|
49
|
+
* Offers a tool to the assistant while the component is mounted. The handler and confirm text
|
|
50
|
+
* always use the latest render's values; the tool is only registered again when its name,
|
|
51
|
+
* description, label, parameters or whether it confirms change.
|
|
52
|
+
*
|
|
53
|
+
* @example
|
|
54
|
+
* ```tsx
|
|
55
|
+
* useAssistantTool({
|
|
56
|
+
* name: "get_document",
|
|
57
|
+
* description: "The open document: title, summary and text as Markdown.",
|
|
58
|
+
* handler: () => ({ title, summary, markdown }),
|
|
59
|
+
* });
|
|
60
|
+
* ```
|
|
61
|
+
*/
|
|
62
|
+
export declare function useAssistantTool<TArgs = Record<string, unknown>>(tool: AssistantTool<TArgs> | null | false | undefined): void;
|
|
63
|
+
/**
|
|
64
|
+
* Gives the assistant the app's own instructions (its purpose, terms and conventions) while the
|
|
65
|
+
* component is mounted. They are placed under the server's fixed rules, which they cannot
|
|
66
|
+
* override. At most 8000 characters.
|
|
67
|
+
*/
|
|
68
|
+
export declare function useAssistantInstructions(instructions: string | null | undefined): void;
|
|
69
|
+
/**
|
|
70
|
+
* Tells the assistant what the user is looking at (the open record, the filter) while the
|
|
71
|
+
* component is mounted. Data, never followed as instructions. Pass something JSON-serialisable;
|
|
72
|
+
* it is sent again whenever its JSON changes.
|
|
73
|
+
*/
|
|
74
|
+
export declare function useAssistantContext(context: unknown): void;
|
|
75
|
+
export {};
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
import { useEffect, useLayoutEffect, useRef } from "react";
|
|
2
|
+
const CHROME_READY_EVENT = "ob:chrome-ready";
|
|
3
|
+
function currentAssistant() {
|
|
4
|
+
return globalThis.ob?.chrome?.assistant;
|
|
5
|
+
}
|
|
6
|
+
function hasChrome() {
|
|
7
|
+
return Boolean(globalThis.ob?.chrome);
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Calls `use` with the assistant once the chrome is on the page - at once when it already is -
|
|
11
|
+
* and returns a function that undoes it (or stops waiting). Skipped when the assistant is off.
|
|
12
|
+
*/
|
|
13
|
+
export function withAssistant(use) {
|
|
14
|
+
let cleanup;
|
|
15
|
+
let run = () => {
|
|
16
|
+
let assistant = currentAssistant();
|
|
17
|
+
if (assistant?.enabled)
|
|
18
|
+
cleanup = use(assistant);
|
|
19
|
+
};
|
|
20
|
+
if (hasChrome() || typeof window === "undefined") {
|
|
21
|
+
run();
|
|
22
|
+
return () => cleanup?.();
|
|
23
|
+
}
|
|
24
|
+
window.addEventListener(CHROME_READY_EVENT, run, { once: true });
|
|
25
|
+
return () => {
|
|
26
|
+
window.removeEventListener(CHROME_READY_EVENT, run);
|
|
27
|
+
cleanup?.();
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
/** Whether the assistant is enabled on this page (the chrome is mounted and the feature is on). */
|
|
31
|
+
export function isAssistantEnabled() {
|
|
32
|
+
return currentAssistant()?.enabled === true;
|
|
33
|
+
}
|
|
34
|
+
/** Opens the assistant panel, when the assistant is enabled. */
|
|
35
|
+
export function openAssistant() {
|
|
36
|
+
currentAssistant()?.open();
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Offers a tool to the assistant while the component is mounted. The handler and confirm text
|
|
40
|
+
* always use the latest render's values; the tool is only registered again when its name,
|
|
41
|
+
* description, label, parameters or whether it confirms change.
|
|
42
|
+
*
|
|
43
|
+
* @example
|
|
44
|
+
* ```tsx
|
|
45
|
+
* useAssistantTool({
|
|
46
|
+
* name: "get_document",
|
|
47
|
+
* description: "The open document: title, summary and text as Markdown.",
|
|
48
|
+
* handler: () => ({ title, summary, markdown }),
|
|
49
|
+
* });
|
|
50
|
+
* ```
|
|
51
|
+
*/
|
|
52
|
+
export function useAssistantTool(tool) {
|
|
53
|
+
// The handler is called long after the render that registered it; it reads the latest tool.
|
|
54
|
+
let latest = useRef(tool);
|
|
55
|
+
useLayoutEffect(() => {
|
|
56
|
+
latest.current = tool;
|
|
57
|
+
});
|
|
58
|
+
let key = tool
|
|
59
|
+
? JSON.stringify([tool.name, tool.description, tool.label ?? null, tool.parameters ?? null, Boolean(tool.confirm)])
|
|
60
|
+
: null;
|
|
61
|
+
useEffect(() => {
|
|
62
|
+
let current = latest.current;
|
|
63
|
+
if (!key || !current)
|
|
64
|
+
return;
|
|
65
|
+
let { name, description, label, parameters, confirm } = current;
|
|
66
|
+
return withAssistant((assistant) => assistant.registerTool({
|
|
67
|
+
name,
|
|
68
|
+
description,
|
|
69
|
+
label,
|
|
70
|
+
parameters,
|
|
71
|
+
handler: (args) => {
|
|
72
|
+
let live = latest.current;
|
|
73
|
+
if (!live)
|
|
74
|
+
throw new Error(`The tool "${name}" is no longer available.`);
|
|
75
|
+
return live.handler(args);
|
|
76
|
+
},
|
|
77
|
+
confirm: confirm
|
|
78
|
+
? (args) => {
|
|
79
|
+
let live = latest.current ? latest.current.confirm : undefined;
|
|
80
|
+
return typeof live === "function" ? live(args) : "";
|
|
81
|
+
}
|
|
82
|
+
: undefined,
|
|
83
|
+
}));
|
|
84
|
+
}, [key]);
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Gives the assistant the app's own instructions (its purpose, terms and conventions) while the
|
|
88
|
+
* component is mounted. They are placed under the server's fixed rules, which they cannot
|
|
89
|
+
* override. At most 8000 characters.
|
|
90
|
+
*/
|
|
91
|
+
export function useAssistantInstructions(instructions) {
|
|
92
|
+
useEffect(() => {
|
|
93
|
+
if (!instructions)
|
|
94
|
+
return;
|
|
95
|
+
return withAssistant((assistant) => {
|
|
96
|
+
assistant.setInstructions?.(instructions);
|
|
97
|
+
return () => assistant.setInstructions?.(null);
|
|
98
|
+
});
|
|
99
|
+
}, [instructions]);
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* Tells the assistant what the user is looking at (the open record, the filter) while the
|
|
103
|
+
* component is mounted. Data, never followed as instructions. Pass something JSON-serialisable;
|
|
104
|
+
* it is sent again whenever its JSON changes.
|
|
105
|
+
*/
|
|
106
|
+
export function useAssistantContext(context) {
|
|
107
|
+
let json = context == null ? null : JSON.stringify(context);
|
|
108
|
+
useEffect(() => {
|
|
109
|
+
if (json == null)
|
|
110
|
+
return;
|
|
111
|
+
return withAssistant((assistant) => {
|
|
112
|
+
assistant.setContext(JSON.parse(json));
|
|
113
|
+
return () => assistant.setContext(null);
|
|
114
|
+
});
|
|
115
|
+
}, [json]);
|
|
116
|
+
}
|
package/es/index.d.ts
CHANGED
|
@@ -9,6 +9,7 @@ export { ChipListInput, type ChipListInputProps, FilterBuilder, type FilterBuild
|
|
|
9
9
|
export { Card, LinkedList, LinkedListItem } from "./components/LinkedCardList/index.js";
|
|
10
10
|
export { MergeProgressDialogDs, type MergeProgressDialogDsProps, } from "./components/MergeProgressDialog/MergeProgressDialogDs.js";
|
|
11
11
|
export { type MergeJobOptions, type MergePhase, useMergeJob } from "./components/MergeProgressDialog/useMergeJob.js";
|
|
12
|
+
export { type AssistantTool, type AssistantToolParameters, isAssistantEnabled, openAssistant, useAssistantContext, useAssistantInstructions, useAssistantTool, } from "./chrome/assistant.js";
|
|
12
13
|
export { type OpenReportOptions, openReport } from "./chrome/openReport.js";
|
|
13
14
|
export { BannerImage as PageBannerImage, type BannerImageProps, PageBanner, type PageBannerProps, Tab as PageBannerTab, TabList as PageBannerTabList, type TabListProps as PageBannerTabListProps, type TabProps as PageBannerTabProps, Title as PageBannerTitle, type TitleProps as PageBannerTitleProps, } from "./components/PageBanner/index.js";
|
|
14
15
|
export { Portal } from "./components/Portal/index.js";
|
package/es/index.js
CHANGED
|
@@ -11,6 +11,7 @@ export { ChipListInput, FilterBuilder, FilterEditor, FilterGroupEditor, FilterNa
|
|
|
11
11
|
export { Card, LinkedList, LinkedListItem } from "./components/LinkedCardList/index.js";
|
|
12
12
|
export { MergeProgressDialogDs, } from "./components/MergeProgressDialog/MergeProgressDialogDs.js";
|
|
13
13
|
export { useMergeJob } from "./components/MergeProgressDialog/useMergeJob.js";
|
|
14
|
+
export { isAssistantEnabled, openAssistant, useAssistantContext, useAssistantInstructions, useAssistantTool, } from "./chrome/assistant.js";
|
|
14
15
|
export { openReport } from "./chrome/openReport.js";
|
|
15
16
|
export { BannerImage as PageBannerImage, PageBanner, Tab as PageBannerTab, TabList as PageBannerTabList, Title as PageBannerTitle, } from "./components/PageBanner/index.js";
|
|
16
17
|
// PdfViewer is intentionally not re-exported here. It references the pdf.js worker
|
package/package.json
CHANGED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
import { act, render } from "@testing-library/react";
|
|
2
|
+
import { afterEach, describe, expect, it, vi } from "vitest";
|
|
3
|
+
|
|
4
|
+
import { useAssistantContext, useAssistantInstructions, useAssistantTool } from "./assistant";
|
|
5
|
+
|
|
6
|
+
let globals = globalThis as { ob?: unknown };
|
|
7
|
+
|
|
8
|
+
function fakeAssistant(enabled = true) {
|
|
9
|
+
let tools = new Map<string, any>();
|
|
10
|
+
let assistant = {
|
|
11
|
+
enabled,
|
|
12
|
+
tools,
|
|
13
|
+
instructions: null as string | null,
|
|
14
|
+
context: null as unknown,
|
|
15
|
+
registerTool: vi.fn((tool: any) => {
|
|
16
|
+
tools.set(tool.name, tool);
|
|
17
|
+
return () => tools.delete(tool.name);
|
|
18
|
+
}),
|
|
19
|
+
setInstructions: vi.fn((value: string | null) => {
|
|
20
|
+
assistant.instructions = value;
|
|
21
|
+
}),
|
|
22
|
+
setContext: vi.fn((value: unknown) => {
|
|
23
|
+
assistant.context = value;
|
|
24
|
+
}),
|
|
25
|
+
open: vi.fn(),
|
|
26
|
+
close: vi.fn(),
|
|
27
|
+
};
|
|
28
|
+
return assistant;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function Tool({ title }: { title: string }) {
|
|
32
|
+
useAssistantTool({
|
|
33
|
+
name: "get_title",
|
|
34
|
+
description: "The title",
|
|
35
|
+
handler: () => title,
|
|
36
|
+
});
|
|
37
|
+
return null;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
afterEach(() => {
|
|
41
|
+
delete globals.ob;
|
|
42
|
+
vi.restoreAllMocks();
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
describe("useAssistantTool", () => {
|
|
46
|
+
it("registers while mounted and uses the latest handler without registering again", async () => {
|
|
47
|
+
let assistant = fakeAssistant();
|
|
48
|
+
globals.ob = { chrome: { assistant } };
|
|
49
|
+
|
|
50
|
+
let view = render(<Tool title="Første" />);
|
|
51
|
+
view.rerender(<Tool title="Andre" />);
|
|
52
|
+
|
|
53
|
+
expect(assistant.registerTool).toHaveBeenCalledTimes(1);
|
|
54
|
+
expect(await assistant.tools.get("get_title").handler({})).toBe("Andre");
|
|
55
|
+
|
|
56
|
+
view.unmount();
|
|
57
|
+
expect(assistant.tools.size).toBe(0);
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
it("waits for the chrome when the app starts first", () => {
|
|
61
|
+
let view = render(<Tool title="x" />);
|
|
62
|
+
let assistant = fakeAssistant();
|
|
63
|
+
globals.ob = { chrome: { assistant } };
|
|
64
|
+
|
|
65
|
+
act(() => {
|
|
66
|
+
window.dispatchEvent(new CustomEvent("ob:chrome-ready"));
|
|
67
|
+
});
|
|
68
|
+
expect(assistant.tools.has("get_title")).toBe(true);
|
|
69
|
+
view.unmount();
|
|
70
|
+
});
|
|
71
|
+
|
|
72
|
+
it("does nothing when the assistant is off", () => {
|
|
73
|
+
let assistant = fakeAssistant(false);
|
|
74
|
+
globals.ob = { chrome: { assistant } };
|
|
75
|
+
render(<Tool title="x" />);
|
|
76
|
+
expect(assistant.registerTool).not.toHaveBeenCalled();
|
|
77
|
+
});
|
|
78
|
+
|
|
79
|
+
it("does nothing without the chrome", () => {
|
|
80
|
+
expect(() => render(<Tool title="x" />)).not.toThrow();
|
|
81
|
+
});
|
|
82
|
+
});
|
|
83
|
+
|
|
84
|
+
describe("useAssistantInstructions and useAssistantContext", () => {
|
|
85
|
+
function Both({ document }: { document: string }) {
|
|
86
|
+
useAssistantInstructions("Skriv på bokmål.");
|
|
87
|
+
useAssistantContext({ document });
|
|
88
|
+
return null;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
it("sets them while mounted and clears them after", () => {
|
|
92
|
+
let assistant = fakeAssistant();
|
|
93
|
+
globals.ob = { chrome: { assistant } };
|
|
94
|
+
|
|
95
|
+
let view = render(<Both document="HMS" />);
|
|
96
|
+
expect(assistant.instructions).toBe("Skriv på bokmål.");
|
|
97
|
+
expect(assistant.context).toEqual({ document: "HMS" });
|
|
98
|
+
|
|
99
|
+
view.rerender(<Both document="Avvik" />);
|
|
100
|
+
expect(assistant.context).toEqual({ document: "Avvik" });
|
|
101
|
+
|
|
102
|
+
view.unmount();
|
|
103
|
+
expect(assistant.instructions).toBeNull();
|
|
104
|
+
expect(assistant.context).toBeNull();
|
|
105
|
+
});
|
|
106
|
+
});
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
import { useEffect, useLayoutEffect, useRef } from "react";
|
|
2
|
+
|
|
3
|
+
/*
|
|
4
|
+
* Apps offer the site chrome's assistant their own tools, instructions and context. The
|
|
5
|
+
* assistant lives in the `@olenbetong/synergi-chrome` bundle the 2026 templates load, so an app
|
|
6
|
+
* never bundles it: these hooks forward to `window.ob.chrome.assistant`, waiting for the chrome
|
|
7
|
+
* to mount (`ob:chrome-ready`) when the app starts first. On a page without the chrome, or where
|
|
8
|
+
* the article feature `assistant` is off, they do nothing.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
/** A JSON Schema object describing a tool's arguments. */
|
|
12
|
+
export type AssistantToolParameters = {
|
|
13
|
+
type: "object";
|
|
14
|
+
properties?: Record<string, unknown>;
|
|
15
|
+
required?: string[];
|
|
16
|
+
[key: string]: unknown;
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* A tool the app offers the assistant. The handler runs in the page with the user's own
|
|
21
|
+
* permissions; what it returns (JSON-serialisable) is what the model sees.
|
|
22
|
+
*/
|
|
23
|
+
export type AssistantTool<TArgs = Record<string, unknown>> = {
|
|
24
|
+
/** Letters, digits, `_` and `-`, at most 64 characters; unique on the page. */
|
|
25
|
+
name: string;
|
|
26
|
+
/** What the tool does and when to use it. The model reads this to decide. */
|
|
27
|
+
description: string;
|
|
28
|
+
/**
|
|
29
|
+
* A few words for the user, shown in the panel when the tool has run ("Read the open document"),
|
|
30
|
+
* in their language. Never sent to the model. Without it the panel shows the name.
|
|
31
|
+
*/
|
|
32
|
+
label?: string;
|
|
33
|
+
/** The arguments, as a JSON Schema object. Leave out for a tool without arguments. */
|
|
34
|
+
parameters?: AssistantToolParameters;
|
|
35
|
+
handler: (args: TArgs) => unknown | Promise<unknown>;
|
|
36
|
+
/**
|
|
37
|
+
* Ask the user before running: `true` for a generic question, or a function returning the
|
|
38
|
+
* question for these arguments. Use it for every tool that changes something.
|
|
39
|
+
*/
|
|
40
|
+
confirm?: boolean | ((args: TArgs) => string);
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
type AssistantApi = {
|
|
44
|
+
readonly enabled: boolean;
|
|
45
|
+
registerTool: (tool: AssistantTool<any>) => () => void;
|
|
46
|
+
setInstructions?: (instructions: string | null) => void;
|
|
47
|
+
setContext: (context: unknown) => void;
|
|
48
|
+
open: () => void;
|
|
49
|
+
close: () => void;
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
const CHROME_READY_EVENT = "ob:chrome-ready";
|
|
53
|
+
|
|
54
|
+
function currentAssistant(): AssistantApi | undefined {
|
|
55
|
+
return (globalThis as { ob?: { chrome?: { assistant?: AssistantApi } } }).ob?.chrome?.assistant;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function hasChrome() {
|
|
59
|
+
return Boolean((globalThis as { ob?: { chrome?: unknown } }).ob?.chrome);
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Calls `use` with the assistant once the chrome is on the page - at once when it already is -
|
|
64
|
+
* and returns a function that undoes it (or stops waiting). Skipped when the assistant is off.
|
|
65
|
+
*/
|
|
66
|
+
export function withAssistant(use: (assistant: AssistantApi) => void | (() => void)): () => void {
|
|
67
|
+
let cleanup: void | (() => void);
|
|
68
|
+
let run = () => {
|
|
69
|
+
let assistant = currentAssistant();
|
|
70
|
+
if (assistant?.enabled) cleanup = use(assistant);
|
|
71
|
+
};
|
|
72
|
+
|
|
73
|
+
if (hasChrome() || typeof window === "undefined") {
|
|
74
|
+
run();
|
|
75
|
+
return () => cleanup?.();
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
window.addEventListener(CHROME_READY_EVENT, run, { once: true });
|
|
79
|
+
return () => {
|
|
80
|
+
window.removeEventListener(CHROME_READY_EVENT, run);
|
|
81
|
+
cleanup?.();
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Whether the assistant is enabled on this page (the chrome is mounted and the feature is on). */
|
|
86
|
+
export function isAssistantEnabled() {
|
|
87
|
+
return currentAssistant()?.enabled === true;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** Opens the assistant panel, when the assistant is enabled. */
|
|
91
|
+
export function openAssistant() {
|
|
92
|
+
currentAssistant()?.open();
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Offers a tool to the assistant while the component is mounted. The handler and confirm text
|
|
97
|
+
* always use the latest render's values; the tool is only registered again when its name,
|
|
98
|
+
* description, label, parameters or whether it confirms change.
|
|
99
|
+
*
|
|
100
|
+
* @example
|
|
101
|
+
* ```tsx
|
|
102
|
+
* useAssistantTool({
|
|
103
|
+
* name: "get_document",
|
|
104
|
+
* description: "The open document: title, summary and text as Markdown.",
|
|
105
|
+
* handler: () => ({ title, summary, markdown }),
|
|
106
|
+
* });
|
|
107
|
+
* ```
|
|
108
|
+
*/
|
|
109
|
+
export function useAssistantTool<TArgs = Record<string, unknown>>(
|
|
110
|
+
tool: AssistantTool<TArgs> | null | false | undefined,
|
|
111
|
+
) {
|
|
112
|
+
// The handler is called long after the render that registered it; it reads the latest tool.
|
|
113
|
+
let latest = useRef(tool);
|
|
114
|
+
useLayoutEffect(() => {
|
|
115
|
+
latest.current = tool;
|
|
116
|
+
});
|
|
117
|
+
|
|
118
|
+
let key = tool
|
|
119
|
+
? JSON.stringify([tool.name, tool.description, tool.label ?? null, tool.parameters ?? null, Boolean(tool.confirm)])
|
|
120
|
+
: null;
|
|
121
|
+
|
|
122
|
+
useEffect(() => {
|
|
123
|
+
let current = latest.current;
|
|
124
|
+
if (!key || !current) return;
|
|
125
|
+
let { name, description, label, parameters, confirm } = current;
|
|
126
|
+
|
|
127
|
+
return withAssistant((assistant) =>
|
|
128
|
+
assistant.registerTool({
|
|
129
|
+
name,
|
|
130
|
+
description,
|
|
131
|
+
label,
|
|
132
|
+
parameters,
|
|
133
|
+
handler: (args: TArgs) => {
|
|
134
|
+
let live = latest.current;
|
|
135
|
+
if (!live) throw new Error(`The tool "${name}" is no longer available.`);
|
|
136
|
+
return live.handler(args);
|
|
137
|
+
},
|
|
138
|
+
confirm: confirm
|
|
139
|
+
? (args: TArgs) => {
|
|
140
|
+
let live = latest.current ? latest.current.confirm : undefined;
|
|
141
|
+
return typeof live === "function" ? live(args) : "";
|
|
142
|
+
}
|
|
143
|
+
: undefined,
|
|
144
|
+
}),
|
|
145
|
+
);
|
|
146
|
+
}, [key]);
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/**
|
|
150
|
+
* Gives the assistant the app's own instructions (its purpose, terms and conventions) while the
|
|
151
|
+
* component is mounted. They are placed under the server's fixed rules, which they cannot
|
|
152
|
+
* override. At most 8000 characters.
|
|
153
|
+
*/
|
|
154
|
+
export function useAssistantInstructions(instructions: string | null | undefined) {
|
|
155
|
+
useEffect(() => {
|
|
156
|
+
if (!instructions) return;
|
|
157
|
+
return withAssistant((assistant) => {
|
|
158
|
+
assistant.setInstructions?.(instructions);
|
|
159
|
+
return () => assistant.setInstructions?.(null);
|
|
160
|
+
});
|
|
161
|
+
}, [instructions]);
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/**
|
|
165
|
+
* Tells the assistant what the user is looking at (the open record, the filter) while the
|
|
166
|
+
* component is mounted. Data, never followed as instructions. Pass something JSON-serialisable;
|
|
167
|
+
* it is sent again whenever its JSON changes.
|
|
168
|
+
*/
|
|
169
|
+
export function useAssistantContext(context: unknown) {
|
|
170
|
+
let json = context == null ? null : JSON.stringify(context);
|
|
171
|
+
useEffect(() => {
|
|
172
|
+
if (json == null) return;
|
|
173
|
+
return withAssistant((assistant) => {
|
|
174
|
+
assistant.setContext(JSON.parse(json));
|
|
175
|
+
return () => assistant.setContext(null);
|
|
176
|
+
});
|
|
177
|
+
}, [json]);
|
|
178
|
+
}
|
package/src/index.ts
CHANGED
|
@@ -48,6 +48,15 @@ export {
|
|
|
48
48
|
type MergeProgressDialogDsProps,
|
|
49
49
|
} from "./components/MergeProgressDialog/MergeProgressDialogDs.js";
|
|
50
50
|
export { type MergeJobOptions, type MergePhase, useMergeJob } from "./components/MergeProgressDialog/useMergeJob.js";
|
|
51
|
+
export {
|
|
52
|
+
type AssistantTool,
|
|
53
|
+
type AssistantToolParameters,
|
|
54
|
+
isAssistantEnabled,
|
|
55
|
+
openAssistant,
|
|
56
|
+
useAssistantContext,
|
|
57
|
+
useAssistantInstructions,
|
|
58
|
+
useAssistantTool,
|
|
59
|
+
} from "./chrome/assistant.js";
|
|
51
60
|
export { type OpenReportOptions, openReport } from "./chrome/openReport.js";
|
|
52
61
|
export {
|
|
53
62
|
BannerImage as PageBannerImage,
|