@hey-research-lab/virtuals-plugin 0.0.0-stage → 0.1.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.
Files changed (10) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/LICENSE +21 -0
  3. package/README.md +245 -2
  4. package/dist/acp.d.ts +257 -0
  5. package/dist/acp.js +812 -0
  6. package/dist/index.cjs +877 -0
  7. package/dist/index.d.cts +161 -0
  8. package/dist/index.d.ts +161 -0
  9. package/dist/index.js +831 -0
  10. package/package.json +93 -3
package/dist/index.d.cts ADDED
@@ -0,0 +1,161 @@
1
+ import { GameFunction, GameWorker, ExecutableGameFunctionResponse } from '@virtuals-protocol/game';
2
+ import { FetchLike, HeyClient, HeyAgentResponse } from '@hey-research-lab/sdk';
3
+
4
+ /** How the plugin reaches HEY. Everything is optional: with nothing set it reads the public API anonymously. */
5
+ type HeyPluginOptions = {
6
+ /**
7
+ * A HEY API key from heyresearch.xyz/account. Optional: it lifts the anonymous rate limit and
8
+ * nothing else. Defaults to `HEY_API_KEY` from the environment. Sent as a bearer token, never logged.
9
+ */
10
+ apiKey?: string;
11
+ /**
12
+ * Defaults to https://heyresearch.xyz. Only for tests and local mocks: `https:` or
13
+ * `http://localhost` / `http://127.0.0.1`. It is not a network switch.
14
+ */
15
+ baseUrl?: string;
16
+ /** For tests and exotic runtimes; the global `fetch` by default. */
17
+ fetchImpl?: FetchLike;
18
+ /** Milliseconds before a HEY read is abandoned; the SDK's default is 15 000. */
19
+ timeoutMs?: number;
20
+ /** A ready client, when the host already has one. Overrides the four fields above. */
21
+ client?: HeyClient;
22
+ };
23
+ declare class InvalidBaseUrlError extends Error {
24
+ readonly code = "invalid_base_url";
25
+ constructor();
26
+ }
27
+ declare function createHeyClient(options?: HeyPluginOptions): HeyClient;
28
+
29
+ /**
30
+ * What one HEY read produced, before a framework wraps it.
31
+ *
32
+ * - `answer`: HEY answered about a project or the chain.
33
+ * - `not_found` / `ambiguous`: HEY answered that it holds no such project, or several match. These
34
+ * are answers too (a reading of HEY's index), so `ok` is true.
35
+ * - `invalid` / `error`: the request was malformed, refused, or HEY could not be read.
36
+ */
37
+ type HeyOutcome = 'answer' | 'not_found' | 'ambiguous' | 'invalid' | 'error';
38
+ type HeyResult = {
39
+ ok: boolean;
40
+ outcome: HeyOutcome;
41
+ /** The text an agent reads: HEY's semantics kept, ending with the attribution line. */
42
+ text: string;
43
+ projectUrl?: string;
44
+ asOf?: string;
45
+ citation?: HeyAgentResponse['citation'];
46
+ error?: {
47
+ code: string;
48
+ message: string;
49
+ retryable: boolean;
50
+ status?: number;
51
+ retryAfterSeconds?: number;
52
+ requestId?: string;
53
+ };
54
+ };
55
+
56
+ declare const HEY_FUNCTION_NAMES: readonly ["hey_research_project", "hey_find_projects", "hey_recent_changes", "hey_project_timeline", "hey_chain_overview"];
57
+ type HeyFunctionName = (typeof HEY_FUNCTION_NAMES)[number];
58
+ declare const HEY_WORKER_ID = "hey_research_worker";
59
+ declare const HEY_WORKER_NAME = "HEY Research \u2014 Robinhood Chain builders";
60
+ declare const HEY_WORKER_DESCRIPTION: string;
61
+ type HeyFunctionOptions = HeyPluginOptions & {
62
+ /** The clock for "read at" lines; tests pin it. */
63
+ now?: () => Date;
64
+ };
65
+ type HeyResearchWorkerOptions = HeyFunctionOptions & {
66
+ /** Defaults to `hey_research_worker`. */
67
+ id?: string;
68
+ name?: string;
69
+ description?: string;
70
+ /** Replace the default environment the worker reports to GAME. */
71
+ getEnvironment?: () => Promise<Record<string, unknown>>;
72
+ };
73
+ /** HEY's answer as GAME's response: Done for an answer (including "HEY holds no such project"), Failed otherwise. */
74
+ declare function toGameResponse(result: HeyResult): ExecutableGameFunctionResponse;
75
+ /**
76
+ * The five HEY functions, each one SDK read. Compose them into your own worker, or use
77
+ * `heyResearchWorker` for a ready one.
78
+ */
79
+ declare function heyResearchFunctions(options?: HeyFunctionOptions): GameFunction<({
80
+ name: string;
81
+ description: string;
82
+ type: string;
83
+ optional: boolean;
84
+ } | {
85
+ name: string;
86
+ description: string;
87
+ type: string;
88
+ })[]>[];
89
+ /** The environment the worker reports to GAME each step: what it covers and how to cite it. */
90
+ declare function heyEnvironment(): Promise<Record<string, unknown>>;
91
+ /**
92
+ * A ready GAME worker with the five HEY functions.
93
+ *
94
+ * ```ts
95
+ * const agent = new GameAgent(process.env.GAME_API_KEY!, {
96
+ * name: 'Robinhood Chain scout', goal: '…', description: '…',
97
+ * workers: [heyResearchWorker()],
98
+ * });
99
+ * ```
100
+ */
101
+ declare function heyResearchWorker(options?: HeyResearchWorkerOptions): GameWorker;
102
+
103
+ /**
104
+ * The five HEY reads the plugin offers, framework-neutral. Each maps to one SDK read (research
105
+ * resolves a contract or ticker first) and renders HEY's answer as text that keeps its semantics:
106
+ * unknown stays unknown, market data is context, every answer carries its link, its as-of time and
107
+ * the attribution line. The GAME worker and the ACP seller both call these.
108
+ */
109
+
110
+ type ReadContext = {
111
+ hey: HeyClient;
112
+ now?: () => Date;
113
+ };
114
+ /**
115
+ * A chain id as a framework passes it (a string, usually) or as JSON carries it. Absent means
116
+ * Robinhood Chain; `4663` and `eip155:4663` are accepted; anything else is `unsupported_chain`.
117
+ */
118
+ declare function checkChain(value: unknown): HeyResult | null;
119
+ /**
120
+ * Research one project by HEY slug, `$TICKER`, name or 0x contract address on Robinhood Chain.
121
+ * A contract resolves through `token.lookup`; a slug goes straight to the agent contract's
122
+ * `research_project`; a ticker or name goes through HEY's search and is researched only when one
123
+ * published project matches it exactly.
124
+ */
125
+ declare function researchProject(ctx: ReadContext, rawQuery: string | undefined): Promise<HeyResult>;
126
+ /** Search HEY's index by name, ticker or contract: published projects, launch records and issuer tokens, each labelled. */
127
+ declare function findProjects(ctx: ReadContext, rawQuery: string | undefined): Promise<HeyResult>;
128
+ type ChangesArgs = {
129
+ project?: string | undefined;
130
+ days?: string | number | undefined;
131
+ limit?: string | number | undefined;
132
+ buildingOnly?: string | boolean | undefined;
133
+ };
134
+ /** The canonical change ledger through the agent contract's `what_changed`: the true total, by type, newest first. */
135
+ declare function recentChanges(ctx: ReadContext, args: ChangesArgs): Promise<HeyResult>;
136
+ /** One project's timeline, newest first: ships with their verification and whether they count as building. */
137
+ declare function projectTimeline(ctx: ReadContext, rawProject: string | undefined, rawLimit?: string | number): Promise<HeyResult>;
138
+ /** Robinhood Chain day by day: HEY's building counts first, the chain's activity next, DEX figures as market context. */
139
+ declare function chainOverview(ctx: ReadContext, rawDays?: string | number): Promise<HeyResult>;
140
+
141
+ /** The line every answer ends with, so an agent cites HEY. */
142
+ declare const ATTRIBUTION = "Source: HEY Research Lab \u2014 heyresearch.xyz";
143
+ declare function sourceLine(link?: string | null): string;
144
+
145
+ declare const CHAIN_NAME: "Robinhood Chain";
146
+ declare const CHAIN_ID: 4663;
147
+ declare const CAIP2: "eip155:4663";
148
+ declare class UnsupportedChainError extends Error {
149
+ readonly chainId: unknown;
150
+ readonly code = "unsupported_chain";
151
+ constructor(chainId: unknown);
152
+ }
153
+ /** Accepts the integer 4663 only. Strings, 4663.0, "04663", other chains → UnsupportedChainError. */
154
+ declare function assertChainId(value: unknown): asserts value is typeof CHAIN_ID;
155
+
156
+ /** The package version; a test holds it equal to package.json. */
157
+ declare const VERSION = "0.1.0";
158
+ /** Sent to HEY as `x-hey-integration` so the lab can count this plugin's calls by version. */
159
+ declare const INTEGRATION = "hey-virtuals-plugin/0.1.0";
160
+
161
+ export { ATTRIBUTION, CAIP2, CHAIN_ID, CHAIN_NAME, type ChangesArgs, HEY_FUNCTION_NAMES, HEY_WORKER_DESCRIPTION, HEY_WORKER_ID, HEY_WORKER_NAME, type HeyFunctionName, type HeyFunctionOptions, type HeyOutcome, type HeyPluginOptions, type HeyResearchWorkerOptions, type HeyResult, INTEGRATION, InvalidBaseUrlError, type ReadContext, UnsupportedChainError, VERSION, assertChainId, chainOverview, checkChain, createHeyClient, findProjects, heyEnvironment, heyResearchFunctions, heyResearchWorker, projectTimeline, recentChanges, researchProject, sourceLine, toGameResponse };
package/dist/index.d.ts ADDED
@@ -0,0 +1,161 @@
1
+ import { GameFunction, GameWorker, ExecutableGameFunctionResponse } from '@virtuals-protocol/game';
2
+ import { FetchLike, HeyClient, HeyAgentResponse } from '@hey-research-lab/sdk';
3
+
4
+ /** How the plugin reaches HEY. Everything is optional: with nothing set it reads the public API anonymously. */
5
+ type HeyPluginOptions = {
6
+ /**
7
+ * A HEY API key from heyresearch.xyz/account. Optional: it lifts the anonymous rate limit and
8
+ * nothing else. Defaults to `HEY_API_KEY` from the environment. Sent as a bearer token, never logged.
9
+ */
10
+ apiKey?: string;
11
+ /**
12
+ * Defaults to https://heyresearch.xyz. Only for tests and local mocks: `https:` or
13
+ * `http://localhost` / `http://127.0.0.1`. It is not a network switch.
14
+ */
15
+ baseUrl?: string;
16
+ /** For tests and exotic runtimes; the global `fetch` by default. */
17
+ fetchImpl?: FetchLike;
18
+ /** Milliseconds before a HEY read is abandoned; the SDK's default is 15 000. */
19
+ timeoutMs?: number;
20
+ /** A ready client, when the host already has one. Overrides the four fields above. */
21
+ client?: HeyClient;
22
+ };
23
+ declare class InvalidBaseUrlError extends Error {
24
+ readonly code = "invalid_base_url";
25
+ constructor();
26
+ }
27
+ declare function createHeyClient(options?: HeyPluginOptions): HeyClient;
28
+
29
+ /**
30
+ * What one HEY read produced, before a framework wraps it.
31
+ *
32
+ * - `answer`: HEY answered about a project or the chain.
33
+ * - `not_found` / `ambiguous`: HEY answered that it holds no such project, or several match. These
34
+ * are answers too (a reading of HEY's index), so `ok` is true.
35
+ * - `invalid` / `error`: the request was malformed, refused, or HEY could not be read.
36
+ */
37
+ type HeyOutcome = 'answer' | 'not_found' | 'ambiguous' | 'invalid' | 'error';
38
+ type HeyResult = {
39
+ ok: boolean;
40
+ outcome: HeyOutcome;
41
+ /** The text an agent reads: HEY's semantics kept, ending with the attribution line. */
42
+ text: string;
43
+ projectUrl?: string;
44
+ asOf?: string;
45
+ citation?: HeyAgentResponse['citation'];
46
+ error?: {
47
+ code: string;
48
+ message: string;
49
+ retryable: boolean;
50
+ status?: number;
51
+ retryAfterSeconds?: number;
52
+ requestId?: string;
53
+ };
54
+ };
55
+
56
+ declare const HEY_FUNCTION_NAMES: readonly ["hey_research_project", "hey_find_projects", "hey_recent_changes", "hey_project_timeline", "hey_chain_overview"];
57
+ type HeyFunctionName = (typeof HEY_FUNCTION_NAMES)[number];
58
+ declare const HEY_WORKER_ID = "hey_research_worker";
59
+ declare const HEY_WORKER_NAME = "HEY Research \u2014 Robinhood Chain builders";
60
+ declare const HEY_WORKER_DESCRIPTION: string;
61
+ type HeyFunctionOptions = HeyPluginOptions & {
62
+ /** The clock for "read at" lines; tests pin it. */
63
+ now?: () => Date;
64
+ };
65
+ type HeyResearchWorkerOptions = HeyFunctionOptions & {
66
+ /** Defaults to `hey_research_worker`. */
67
+ id?: string;
68
+ name?: string;
69
+ description?: string;
70
+ /** Replace the default environment the worker reports to GAME. */
71
+ getEnvironment?: () => Promise<Record<string, unknown>>;
72
+ };
73
+ /** HEY's answer as GAME's response: Done for an answer (including "HEY holds no such project"), Failed otherwise. */
74
+ declare function toGameResponse(result: HeyResult): ExecutableGameFunctionResponse;
75
+ /**
76
+ * The five HEY functions, each one SDK read. Compose them into your own worker, or use
77
+ * `heyResearchWorker` for a ready one.
78
+ */
79
+ declare function heyResearchFunctions(options?: HeyFunctionOptions): GameFunction<({
80
+ name: string;
81
+ description: string;
82
+ type: string;
83
+ optional: boolean;
84
+ } | {
85
+ name: string;
86
+ description: string;
87
+ type: string;
88
+ })[]>[];
89
+ /** The environment the worker reports to GAME each step: what it covers and how to cite it. */
90
+ declare function heyEnvironment(): Promise<Record<string, unknown>>;
91
+ /**
92
+ * A ready GAME worker with the five HEY functions.
93
+ *
94
+ * ```ts
95
+ * const agent = new GameAgent(process.env.GAME_API_KEY!, {
96
+ * name: 'Robinhood Chain scout', goal: '…', description: '…',
97
+ * workers: [heyResearchWorker()],
98
+ * });
99
+ * ```
100
+ */
101
+ declare function heyResearchWorker(options?: HeyResearchWorkerOptions): GameWorker;
102
+
103
+ /**
104
+ * The five HEY reads the plugin offers, framework-neutral. Each maps to one SDK read (research
105
+ * resolves a contract or ticker first) and renders HEY's answer as text that keeps its semantics:
106
+ * unknown stays unknown, market data is context, every answer carries its link, its as-of time and
107
+ * the attribution line. The GAME worker and the ACP seller both call these.
108
+ */
109
+
110
+ type ReadContext = {
111
+ hey: HeyClient;
112
+ now?: () => Date;
113
+ };
114
+ /**
115
+ * A chain id as a framework passes it (a string, usually) or as JSON carries it. Absent means
116
+ * Robinhood Chain; `4663` and `eip155:4663` are accepted; anything else is `unsupported_chain`.
117
+ */
118
+ declare function checkChain(value: unknown): HeyResult | null;
119
+ /**
120
+ * Research one project by HEY slug, `$TICKER`, name or 0x contract address on Robinhood Chain.
121
+ * A contract resolves through `token.lookup`; a slug goes straight to the agent contract's
122
+ * `research_project`; a ticker or name goes through HEY's search and is researched only when one
123
+ * published project matches it exactly.
124
+ */
125
+ declare function researchProject(ctx: ReadContext, rawQuery: string | undefined): Promise<HeyResult>;
126
+ /** Search HEY's index by name, ticker or contract: published projects, launch records and issuer tokens, each labelled. */
127
+ declare function findProjects(ctx: ReadContext, rawQuery: string | undefined): Promise<HeyResult>;
128
+ type ChangesArgs = {
129
+ project?: string | undefined;
130
+ days?: string | number | undefined;
131
+ limit?: string | number | undefined;
132
+ buildingOnly?: string | boolean | undefined;
133
+ };
134
+ /** The canonical change ledger through the agent contract's `what_changed`: the true total, by type, newest first. */
135
+ declare function recentChanges(ctx: ReadContext, args: ChangesArgs): Promise<HeyResult>;
136
+ /** One project's timeline, newest first: ships with their verification and whether they count as building. */
137
+ declare function projectTimeline(ctx: ReadContext, rawProject: string | undefined, rawLimit?: string | number): Promise<HeyResult>;
138
+ /** Robinhood Chain day by day: HEY's building counts first, the chain's activity next, DEX figures as market context. */
139
+ declare function chainOverview(ctx: ReadContext, rawDays?: string | number): Promise<HeyResult>;
140
+
141
+ /** The line every answer ends with, so an agent cites HEY. */
142
+ declare const ATTRIBUTION = "Source: HEY Research Lab \u2014 heyresearch.xyz";
143
+ declare function sourceLine(link?: string | null): string;
144
+
145
+ declare const CHAIN_NAME: "Robinhood Chain";
146
+ declare const CHAIN_ID: 4663;
147
+ declare const CAIP2: "eip155:4663";
148
+ declare class UnsupportedChainError extends Error {
149
+ readonly chainId: unknown;
150
+ readonly code = "unsupported_chain";
151
+ constructor(chainId: unknown);
152
+ }
153
+ /** Accepts the integer 4663 only. Strings, 4663.0, "04663", other chains → UnsupportedChainError. */
154
+ declare function assertChainId(value: unknown): asserts value is typeof CHAIN_ID;
155
+
156
+ /** The package version; a test holds it equal to package.json. */
157
+ declare const VERSION = "0.1.0";
158
+ /** Sent to HEY as `x-hey-integration` so the lab can count this plugin's calls by version. */
159
+ declare const INTEGRATION = "hey-virtuals-plugin/0.1.0";
160
+
161
+ export { ATTRIBUTION, CAIP2, CHAIN_ID, CHAIN_NAME, type ChangesArgs, HEY_FUNCTION_NAMES, HEY_WORKER_DESCRIPTION, HEY_WORKER_ID, HEY_WORKER_NAME, type HeyFunctionName, type HeyFunctionOptions, type HeyOutcome, type HeyPluginOptions, type HeyResearchWorkerOptions, type HeyResult, INTEGRATION, InvalidBaseUrlError, type ReadContext, UnsupportedChainError, VERSION, assertChainId, chainOverview, checkChain, createHeyClient, findProjects, heyEnvironment, heyResearchFunctions, heyResearchWorker, projectTimeline, recentChanges, researchProject, sourceLine, toGameResponse };