@valon-technologies/gestalt 0.0.1-alpha.16 → 0.0.1-alpha.18
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/README.md +70 -80
- package/package.json +2 -2
- package/src/agent-manager.ts +33 -2
- package/src/agent.ts +31 -11
- package/src/api.ts +12 -0
- package/src/authorization.ts +3 -2
- package/src/cache.ts +14 -3
- package/src/http-subject.ts +5 -1
- package/src/index.ts +3 -5
- package/src/indexeddb.ts +3 -2
- package/{gen → src/internal/gen}/v1/agent_pb.ts +280 -201
- package/{gen → src/internal/gen}/v1/authentication_pb.ts +1 -1
- package/{gen → src/internal/gen}/v1/authorization_pb.ts +1 -1
- package/{gen → src/internal/gen}/v1/cache_pb.ts +1 -1
- package/{gen → src/internal/gen}/v1/datastore_pb.ts +1 -1
- package/src/internal/gen/v1/external_credential_pb.ts +679 -0
- package/{gen → src/internal/gen}/v1/plugin_pb.ts +38 -14
- package/{gen → src/internal/gen}/v1/pluginruntime_pb.ts +15 -130
- package/{gen → src/internal/gen}/v1/runtime_pb.ts +1 -1
- package/{gen → src/internal/gen}/v1/s3_pb.ts +1 -1
- package/{gen → src/internal/gen}/v1/secrets_pb.ts +1 -1
- package/{gen → src/internal/gen}/v1/workflow_pb.ts +11 -6
- package/src/invoker.ts +27 -2
- package/src/pluginruntime.ts +2 -27
- package/src/runtime-log-host.ts +29 -3
- package/src/runtime.ts +14 -9
- package/src/s3.ts +43 -7
- package/src/test-agent-contract.ts +43 -0
- package/src/workflow-manager.ts +42 -2
- package/src/workflow.ts +16 -2
- package/tsconfig.json +1 -1
- package/gen/v1/external_credential_pb.ts +0 -274
- /package/{gen → src/internal/gen}/google/rpc/status_pb.ts +0 -0
package/README.md
CHANGED
|
@@ -1,110 +1,90 @@
|
|
|
1
1
|
# Gestalt TypeScript SDK
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
Use the TypeScript SDK to build Bun-based executable Gestalt providers with
|
|
4
|
+
explicit runtime schemas.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
packaged providers built from that same source tree.
|
|
6
|
+
The package is published as `@valon-technologies/gestalt`.
|
|
8
7
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
Point the package at the provider module with a top-level `gestalt.provider`
|
|
12
|
-
property in `package.json`:
|
|
13
|
-
|
|
14
|
-
```json
|
|
15
|
-
{
|
|
16
|
-
"name": "my-provider",
|
|
17
|
-
"version": "0.0.1-alpha.1",
|
|
18
|
-
"dependencies": {
|
|
19
|
-
"@valon-technologies/gestalt": "0.0.1-alpha.13"
|
|
20
|
-
},
|
|
21
|
-
"gestalt": {
|
|
22
|
-
"provider": {
|
|
23
|
-
"kind": "plugin",
|
|
24
|
-
"target": "./provider.ts#plugin"
|
|
25
|
-
}
|
|
26
|
-
}
|
|
27
|
-
}
|
|
8
|
+
```sh
|
|
9
|
+
bun add @valon-technologies/gestalt@0.0.1-alpha.16
|
|
28
10
|
```
|
|
29
11
|
|
|
30
|
-
The target is a relative file path with an optional export suffix. The runtime
|
|
31
|
-
accepts:
|
|
32
|
-
|
|
33
|
-
- `gestalt.provider` as `{ "kind": "...", "target": "./file.ts#export" }`
|
|
34
|
-
- `gestalt.provider` as a string like `"plugin:./provider.ts#plugin"` or `"cache:./cache.ts#provider"`
|
|
35
|
-
|
|
36
|
-
Use `"plugin"` as the kind token for executable plugin providers.
|
|
37
|
-
|
|
38
|
-
If the export suffix is omitted, the runtime looks for `provider`, then
|
|
39
|
-
`plugin`, then the default export.
|
|
40
|
-
|
|
41
|
-
## Authoring
|
|
42
|
-
|
|
43
|
-
Use explicit runtime schemas to define plugin operation inputs and outputs:
|
|
44
|
-
|
|
45
12
|
```ts
|
|
46
|
-
import {
|
|
47
|
-
definePlugin,
|
|
48
|
-
ok,
|
|
49
|
-
operation,
|
|
50
|
-
response,
|
|
51
|
-
s,
|
|
52
|
-
} from "@valon-technologies/gestalt";
|
|
13
|
+
import { definePlugin, ok, operation, s } from "@valon-technologies/gestalt";
|
|
53
14
|
|
|
54
15
|
export const plugin = definePlugin({
|
|
55
|
-
displayName: "
|
|
56
|
-
description: "A provider implemented with the Gestalt TypeScript SDK",
|
|
57
|
-
configure(name, config) {
|
|
58
|
-
console.log("configured", name, config);
|
|
59
|
-
},
|
|
60
|
-
sessionCatalog(request) {
|
|
61
|
-
return {
|
|
62
|
-
name: "example-session",
|
|
63
|
-
operations: [
|
|
64
|
-
{
|
|
65
|
-
id: "session-ping",
|
|
66
|
-
method: "GET",
|
|
67
|
-
},
|
|
68
|
-
],
|
|
69
|
-
};
|
|
70
|
-
},
|
|
16
|
+
displayName: "Search",
|
|
71
17
|
operations: [
|
|
72
18
|
operation({
|
|
73
|
-
id: "
|
|
19
|
+
id: "search",
|
|
74
20
|
method: "GET",
|
|
75
21
|
readOnly: true,
|
|
76
22
|
input: s.object({
|
|
77
|
-
|
|
78
|
-
|
|
23
|
+
query: s.string({ description: "Search query" }),
|
|
24
|
+
limit: s.integer({ description: "Maximum results", default: 10 }),
|
|
79
25
|
}),
|
|
80
26
|
output: s.object({
|
|
81
|
-
|
|
27
|
+
results: s.array(s.string()),
|
|
82
28
|
}),
|
|
83
29
|
async handler(input) {
|
|
84
|
-
return ok({
|
|
85
|
-
message: `Hello, ${input.name}${input.excited ? "!" : "."}`,
|
|
86
|
-
});
|
|
30
|
+
return ok({ results: [input.query].slice(0, input.limit) });
|
|
87
31
|
},
|
|
88
32
|
}),
|
|
89
33
|
],
|
|
90
34
|
});
|
|
91
35
|
```
|
|
92
36
|
|
|
93
|
-
|
|
94
|
-
needs to set a non-200 status. Plain objects with `status` and `body` fields
|
|
95
|
-
are treated as user data.
|
|
37
|
+
## Provider target
|
|
96
38
|
|
|
97
|
-
|
|
39
|
+
Point the package at the provider module with a top-level `gestalt.provider`
|
|
40
|
+
property in `package.json`.
|
|
98
41
|
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"name": "my-provider",
|
|
45
|
+
"version": "0.0.1",
|
|
46
|
+
"private": true,
|
|
47
|
+
"type": "module",
|
|
48
|
+
"dependencies": {
|
|
49
|
+
"@valon-technologies/gestalt": "0.0.1-alpha.16"
|
|
50
|
+
},
|
|
51
|
+
"gestalt": {
|
|
52
|
+
"provider": {
|
|
53
|
+
"kind": "plugin",
|
|
54
|
+
"target": "./provider.ts#plugin"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
106
58
|
```
|
|
107
59
|
|
|
60
|
+
The target is a relative file path with an optional export suffix. If the suffix
|
|
61
|
+
is omitted, the runtime looks for `provider`, then `plugin`, then the default
|
|
62
|
+
export.
|
|
63
|
+
|
|
64
|
+
Use `"plugin"` as the kind token for executable plugin providers. Use an object
|
|
65
|
+
target with an explicit kind for authentication, authorization, cache,
|
|
66
|
+
IndexedDB, S3, secrets, workflow, agent, and hosted-runtime providers.
|
|
67
|
+
|
|
68
|
+
## Public surface
|
|
69
|
+
|
|
70
|
+
The root package exports provider definition helpers:
|
|
71
|
+
|
|
72
|
+
- `definePlugin` for integration operations and session catalogs.
|
|
73
|
+
- `defineAuthenticationProvider` and `defineAuthorizationProvider` for auth
|
|
74
|
+
surfaces.
|
|
75
|
+
- `defineCacheProvider`, `defineIndexedDBProvider`, `defineS3Provider`, and
|
|
76
|
+
`defineSecretsProvider` for host-service backends.
|
|
77
|
+
- `defineWorkflowProvider`, `defineAgentProvider`, and
|
|
78
|
+
`definePluginRuntimeProvider` for workflow, agent, and hosted-runtime
|
|
79
|
+
backends.
|
|
80
|
+
- `s` schema builders for operation input, output, and catalog metadata.
|
|
81
|
+
- Host-service clients for cache, IndexedDB, S3, workflows, agents,
|
|
82
|
+
invocations, and telemetry.
|
|
83
|
+
|
|
84
|
+
TypeScript types are not enough to describe runtime payloads. Use the schema
|
|
85
|
+
builders for every operation input and output that should appear in the
|
|
86
|
+
Gestalt catalog.
|
|
87
|
+
|
|
108
88
|
## Runtime and build entrypoints
|
|
109
89
|
|
|
110
90
|
Source-mode runtime:
|
|
@@ -116,7 +96,7 @@ gestalt-ts-runtime ROOT plugin:./provider.ts#plugin
|
|
|
116
96
|
Release build:
|
|
117
97
|
|
|
118
98
|
```sh
|
|
119
|
-
gestalt-ts-build ROOT
|
|
99
|
+
gestalt-ts-build ROOT plugin:./provider.ts#plugin OUTPUT PROVIDER_NAME GOOS GOARCH
|
|
120
100
|
```
|
|
121
101
|
|
|
122
102
|
The build entrypoint compiles a standalone executable with Bun and bundles the
|
|
@@ -130,6 +110,15 @@ From the repo root:
|
|
|
130
110
|
buf generate --template sdk/proto/buf.typescript.gen.yaml sdk/proto
|
|
131
111
|
```
|
|
132
112
|
|
|
113
|
+
## API reference
|
|
114
|
+
|
|
115
|
+
The TypeDoc reference is generated from the authored public surface plus
|
|
116
|
+
entrypoint shims under `docs/entrypoints`.
|
|
117
|
+
|
|
118
|
+
```sh
|
|
119
|
+
bun run docs:build
|
|
120
|
+
```
|
|
121
|
+
|
|
133
122
|
## Local checks
|
|
134
123
|
|
|
135
124
|
From `sdk/typescript`:
|
|
@@ -139,4 +128,5 @@ export PATH="$HOME/.bun/bin:$PATH"
|
|
|
139
128
|
bun install
|
|
140
129
|
bun run build:proto
|
|
141
130
|
bun run check
|
|
131
|
+
bun run docs:check
|
|
142
132
|
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@valon-technologies/gestalt",
|
|
3
|
-
"version": "0.0.1-alpha.
|
|
3
|
+
"version": "0.0.1-alpha.18",
|
|
4
4
|
"description": "TypeScript SDK for Gestalt executable providers",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"repository": {
|
|
@@ -12,6 +12,7 @@
|
|
|
12
12
|
"./build": "./src/build.ts",
|
|
13
13
|
"./runtime": "./src/runtime.ts",
|
|
14
14
|
"./schema": "./src/schema.ts",
|
|
15
|
+
"./test/agent-contract": "./src/test-agent-contract.ts",
|
|
15
16
|
"./telemetry": "./src/telemetry.ts",
|
|
16
17
|
"./target": "./src/target.ts"
|
|
17
18
|
},
|
|
@@ -21,7 +22,6 @@
|
|
|
21
22
|
},
|
|
22
23
|
"files": [
|
|
23
24
|
"src",
|
|
24
|
-
"gen",
|
|
25
25
|
"README.md",
|
|
26
26
|
"tsconfig.json"
|
|
27
27
|
],
|
package/src/agent-manager.ts
CHANGED
|
@@ -23,47 +23,67 @@ import {
|
|
|
23
23
|
type AgentSession,
|
|
24
24
|
type AgentTurn,
|
|
25
25
|
type AgentTurnEvent,
|
|
26
|
-
} from "
|
|
26
|
+
} from "./internal/gen/v1/agent_pb.ts";
|
|
27
27
|
import type { Request } from "./api.ts";
|
|
28
28
|
|
|
29
|
+
/** Environment variable containing the agent-manager host-service target. */
|
|
29
30
|
export const ENV_AGENT_MANAGER_SOCKET = "GESTALT_AGENT_MANAGER_SOCKET";
|
|
30
|
-
|
|
31
|
+
/** Environment variable containing the optional agent-manager relay token. */
|
|
32
|
+
export const ENV_AGENT_MANAGER_SOCKET_TOKEN =
|
|
33
|
+
`${ENV_AGENT_MANAGER_SOCKET}_TOKEN`;
|
|
31
34
|
const AGENT_MANAGER_RELAY_TOKEN_HEADER = "x-gestalt-host-service-relay-token";
|
|
32
35
|
|
|
36
|
+
/** Shape accepted when creating an agent session through the host manager. */
|
|
33
37
|
export type AgentManagerCreateSessionInput = MessageInitShape<
|
|
34
38
|
typeof AgentManagerCreateSessionRequestSchema
|
|
35
39
|
>;
|
|
40
|
+
/** Shape accepted when fetching an agent session through the host manager. */
|
|
36
41
|
export type AgentManagerGetSessionInput = MessageInitShape<
|
|
37
42
|
typeof AgentManagerGetSessionRequestSchema
|
|
38
43
|
>;
|
|
44
|
+
/** Shape accepted when listing agent sessions through the host manager. */
|
|
39
45
|
export type AgentManagerListSessionsInput = MessageInitShape<
|
|
40
46
|
typeof AgentManagerListSessionsRequestSchema
|
|
41
47
|
>;
|
|
48
|
+
/** Shape accepted when updating an agent session through the host manager. */
|
|
42
49
|
export type AgentManagerUpdateSessionInput = MessageInitShape<
|
|
43
50
|
typeof AgentManagerUpdateSessionRequestSchema
|
|
44
51
|
>;
|
|
52
|
+
/** Shape accepted when creating an agent turn through the host manager. */
|
|
45
53
|
export type AgentManagerCreateTurnInput = MessageInitShape<
|
|
46
54
|
typeof AgentManagerCreateTurnRequestSchema
|
|
47
55
|
>;
|
|
56
|
+
/** Shape accepted when fetching an agent turn through the host manager. */
|
|
48
57
|
export type AgentManagerGetTurnInput = MessageInitShape<
|
|
49
58
|
typeof AgentManagerGetTurnRequestSchema
|
|
50
59
|
>;
|
|
60
|
+
/** Shape accepted when listing agent turns through the host manager. */
|
|
51
61
|
export type AgentManagerListTurnsInput = MessageInitShape<
|
|
52
62
|
typeof AgentManagerListTurnsRequestSchema
|
|
53
63
|
>;
|
|
64
|
+
/** Shape accepted when cancelling an agent turn through the host manager. */
|
|
54
65
|
export type AgentManagerCancelTurnInput = MessageInitShape<
|
|
55
66
|
typeof AgentManagerCancelTurnRequestSchema
|
|
56
67
|
>;
|
|
68
|
+
/** Shape accepted when listing events for an agent turn. */
|
|
57
69
|
export type AgentManagerListTurnEventsInput = MessageInitShape<
|
|
58
70
|
typeof AgentManagerListTurnEventsRequestSchema
|
|
59
71
|
>;
|
|
72
|
+
/** Shape accepted when listing agent interactions. */
|
|
60
73
|
export type AgentManagerListInteractionsInput = MessageInitShape<
|
|
61
74
|
typeof AgentManagerListInteractionsRequestSchema
|
|
62
75
|
>;
|
|
76
|
+
/** Shape accepted when resolving an agent interaction. */
|
|
63
77
|
export type AgentManagerResolveInteractionInput = MessageInitShape<
|
|
64
78
|
typeof AgentManagerResolveInteractionRequestSchema
|
|
65
79
|
>;
|
|
66
80
|
|
|
81
|
+
/**
|
|
82
|
+
* Client for managing agent sessions, turns, events, and interactions.
|
|
83
|
+
*
|
|
84
|
+
* The constructor accepts either a Gestalt request or an invocation token. Each
|
|
85
|
+
* manager call forwards that token to the host service.
|
|
86
|
+
*/
|
|
67
87
|
export class AgentManager {
|
|
68
88
|
private readonly client: Client<typeof AgentManagerHostService>;
|
|
69
89
|
private readonly invocationToken: string;
|
|
@@ -89,6 +109,7 @@ export class AgentManager {
|
|
|
89
109
|
this.client = createClient(AgentManagerHostService, transport);
|
|
90
110
|
}
|
|
91
111
|
|
|
112
|
+
/** Creates an agent session. */
|
|
92
113
|
async createSession(
|
|
93
114
|
request: AgentManagerCreateSessionInput,
|
|
94
115
|
): Promise<AgentSession> {
|
|
@@ -98,6 +119,7 @@ export class AgentManager {
|
|
|
98
119
|
});
|
|
99
120
|
}
|
|
100
121
|
|
|
122
|
+
/** Fetches one agent session. */
|
|
101
123
|
async getSession(request: AgentManagerGetSessionInput): Promise<AgentSession> {
|
|
102
124
|
return await this.client.getSession({
|
|
103
125
|
...request,
|
|
@@ -105,6 +127,7 @@ export class AgentManager {
|
|
|
105
127
|
});
|
|
106
128
|
}
|
|
107
129
|
|
|
130
|
+
/** Lists agent sessions visible to the invocation token. */
|
|
108
131
|
async listSessions(
|
|
109
132
|
request: AgentManagerListSessionsInput = {},
|
|
110
133
|
): Promise<AgentSession[]> {
|
|
@@ -115,6 +138,7 @@ export class AgentManager {
|
|
|
115
138
|
return [...response.sessions];
|
|
116
139
|
}
|
|
117
140
|
|
|
141
|
+
/** Updates mutable fields on an agent session. */
|
|
118
142
|
async updateSession(
|
|
119
143
|
request: AgentManagerUpdateSessionInput,
|
|
120
144
|
): Promise<AgentSession> {
|
|
@@ -124,6 +148,7 @@ export class AgentManager {
|
|
|
124
148
|
});
|
|
125
149
|
}
|
|
126
150
|
|
|
151
|
+
/** Creates an agent turn. */
|
|
127
152
|
async createTurn(request: AgentManagerCreateTurnInput): Promise<AgentTurn> {
|
|
128
153
|
return await this.client.createTurn({
|
|
129
154
|
...request,
|
|
@@ -131,6 +156,7 @@ export class AgentManager {
|
|
|
131
156
|
});
|
|
132
157
|
}
|
|
133
158
|
|
|
159
|
+
/** Fetches one agent turn. */
|
|
134
160
|
async getTurn(request: AgentManagerGetTurnInput): Promise<AgentTurn> {
|
|
135
161
|
return await this.client.getTurn({
|
|
136
162
|
...request,
|
|
@@ -138,6 +164,7 @@ export class AgentManager {
|
|
|
138
164
|
});
|
|
139
165
|
}
|
|
140
166
|
|
|
167
|
+
/** Lists turns for an agent session. */
|
|
141
168
|
async listTurns(request: AgentManagerListTurnsInput): Promise<AgentTurn[]> {
|
|
142
169
|
const response = await this.client.listTurns({
|
|
143
170
|
...request,
|
|
@@ -146,6 +173,7 @@ export class AgentManager {
|
|
|
146
173
|
return [...response.turns];
|
|
147
174
|
}
|
|
148
175
|
|
|
176
|
+
/** Cancels an in-progress agent turn. */
|
|
149
177
|
async cancelTurn(request: AgentManagerCancelTurnInput): Promise<AgentTurn> {
|
|
150
178
|
return await this.client.cancelTurn({
|
|
151
179
|
...request,
|
|
@@ -153,6 +181,7 @@ export class AgentManager {
|
|
|
153
181
|
});
|
|
154
182
|
}
|
|
155
183
|
|
|
184
|
+
/** Lists events emitted for an agent turn. */
|
|
156
185
|
async listTurnEvents(
|
|
157
186
|
request: AgentManagerListTurnEventsInput,
|
|
158
187
|
): Promise<AgentTurnEvent[]> {
|
|
@@ -163,6 +192,7 @@ export class AgentManager {
|
|
|
163
192
|
return [...response.events];
|
|
164
193
|
}
|
|
165
194
|
|
|
195
|
+
/** Lists pending or completed agent interactions. */
|
|
166
196
|
async listInteractions(
|
|
167
197
|
request: AgentManagerListInteractionsInput,
|
|
168
198
|
): Promise<AgentInteraction[]> {
|
|
@@ -173,6 +203,7 @@ export class AgentManager {
|
|
|
173
203
|
return [...response.interactions];
|
|
174
204
|
}
|
|
175
205
|
|
|
206
|
+
/** Resolves an agent interaction with a host response. */
|
|
176
207
|
async resolveInteraction(
|
|
177
208
|
request: AgentManagerResolveInteractionInput,
|
|
178
209
|
): Promise<AgentInteraction> {
|
package/src/agent.ts
CHANGED
|
@@ -65,19 +65,27 @@ import {
|
|
|
65
65
|
type ListAgentProviderTurnEventsRequest,
|
|
66
66
|
type ListAgentProviderTurnsRequest,
|
|
67
67
|
type ListedAgentTool,
|
|
68
|
+
type ResolveAgentConnectionRequest,
|
|
68
69
|
type ResolveAgentProviderInteractionRequest,
|
|
70
|
+
type ResolvedAgentConnection,
|
|
69
71
|
type ResolvedAgentTool,
|
|
70
|
-
type SearchAgentToolsRequest,
|
|
71
|
-
type SearchAgentToolsResponse,
|
|
72
72
|
type UpdateAgentProviderSessionRequest,
|
|
73
|
-
} from "
|
|
73
|
+
} from "./internal/gen/v1/agent_pb.ts";
|
|
74
74
|
import { errorMessage, type MaybePromise } from "./api.ts";
|
|
75
75
|
import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
|
|
76
76
|
|
|
77
|
+
/** Environment variable containing the agent-host service target. */
|
|
77
78
|
export const ENV_AGENT_HOST_SOCKET = "GESTALT_AGENT_HOST_SOCKET";
|
|
79
|
+
/** Environment variable containing the optional agent-host relay token. */
|
|
78
80
|
export const ENV_AGENT_HOST_SOCKET_TOKEN = `${ENV_AGENT_HOST_SOCKET}_TOKEN`;
|
|
79
81
|
const AGENT_HOST_RELAY_TOKEN_HEADER = "x-gestalt-host-service-relay-token";
|
|
80
82
|
|
|
83
|
+
/**
|
|
84
|
+
* Generated agent protocol message types commonly used by authored providers.
|
|
85
|
+
*
|
|
86
|
+
* These are re-exported so provider code can type sessions, turns, messages,
|
|
87
|
+
* interactions, and host-tool requests without importing from `gen`.
|
|
88
|
+
*/
|
|
81
89
|
export type {
|
|
82
90
|
AgentActor,
|
|
83
91
|
AgentInteraction,
|
|
@@ -108,10 +116,10 @@ export type {
|
|
|
108
116
|
ListAgentProviderTurnEventsRequest,
|
|
109
117
|
ListAgentProviderTurnsRequest,
|
|
110
118
|
ListedAgentTool,
|
|
119
|
+
ResolveAgentConnectionRequest,
|
|
111
120
|
ResolveAgentProviderInteractionRequest,
|
|
121
|
+
ResolvedAgentConnection,
|
|
112
122
|
ResolvedAgentTool,
|
|
113
|
-
SearchAgentToolsRequest,
|
|
114
|
-
SearchAgentToolsResponse,
|
|
115
123
|
UpdateAgentProviderSessionRequest,
|
|
116
124
|
};
|
|
117
125
|
export {
|
|
@@ -123,11 +131,13 @@ export {
|
|
|
123
131
|
AgentToolSourceMode,
|
|
124
132
|
};
|
|
125
133
|
|
|
134
|
+
/** JSON-like value accepted for an agent turn display payload. */
|
|
126
135
|
export type AgentTurnDisplayValue =
|
|
127
136
|
| JsonValue
|
|
128
137
|
| Value
|
|
129
138
|
| MessageInitShape<typeof ValueSchema>;
|
|
130
139
|
|
|
140
|
+
/** Initializer for a turn display with JSON-like input/output/error fields. */
|
|
131
141
|
export type AgentTurnDisplayInit = Omit<
|
|
132
142
|
MessageInitShape<typeof AgentTurnDisplaySchema>,
|
|
133
143
|
"$typeName" | "input" | "output" | "error"
|
|
@@ -137,6 +147,7 @@ export type AgentTurnDisplayInit = Omit<
|
|
|
137
147
|
error?: AgentTurnDisplayValue | undefined;
|
|
138
148
|
};
|
|
139
149
|
|
|
150
|
+
/** Initializer for a turn event with authored display payload helpers. */
|
|
140
151
|
export type AgentTurnEventInit = Omit<
|
|
141
152
|
MessageInitShape<typeof AgentTurnEventSchema>,
|
|
142
153
|
"$typeName" | "display"
|
|
@@ -144,6 +155,7 @@ export type AgentTurnEventInit = Omit<
|
|
|
144
155
|
display?: AgentTurnDisplayInit | undefined;
|
|
145
156
|
};
|
|
146
157
|
|
|
158
|
+
/** Handlers and runtime metadata for an agent provider. */
|
|
147
159
|
export interface AgentProviderOptions extends RuntimeProviderOptions {
|
|
148
160
|
createSession?: (
|
|
149
161
|
request: CreateAgentProviderSessionRequest,
|
|
@@ -186,6 +198,7 @@ export interface AgentProviderOptions extends RuntimeProviderOptions {
|
|
|
186
198
|
) => MaybePromise<MessageInitShape<typeof AgentProviderCapabilitiesSchema>>;
|
|
187
199
|
}
|
|
188
200
|
|
|
201
|
+
/** Runtime provider implementation for the Gestalt agent host contract. */
|
|
189
202
|
export class AgentProvider extends RuntimeProvider {
|
|
190
203
|
readonly kind = "agent" as const;
|
|
191
204
|
|
|
@@ -354,6 +367,7 @@ export class AgentProvider extends RuntimeProvider {
|
|
|
354
367
|
}
|
|
355
368
|
}
|
|
356
369
|
|
|
370
|
+
/** Creates an agent provider for export from a provider module. */
|
|
357
371
|
export function defineAgentProvider(options: AgentProviderOptions): AgentProvider {
|
|
358
372
|
return new AgentProvider(options);
|
|
359
373
|
}
|
|
@@ -408,6 +422,7 @@ function isValueInit(value: unknown): value is MessageInitShape<typeof ValueSche
|
|
|
408
422
|
);
|
|
409
423
|
}
|
|
410
424
|
|
|
425
|
+
/** Runtime type guard for agent providers loaded from user modules. */
|
|
411
426
|
export function isAgentProvider(value: unknown): value is AgentProvider {
|
|
412
427
|
return (
|
|
413
428
|
value instanceof AgentProvider ||
|
|
@@ -420,6 +435,7 @@ export function isAgentProvider(value: unknown): value is AgentProvider {
|
|
|
420
435
|
);
|
|
421
436
|
}
|
|
422
437
|
|
|
438
|
+
/** Client for the agent host service available inside agent providers. */
|
|
423
439
|
export class AgentHost {
|
|
424
440
|
private readonly client: Client<typeof AgentHostService>;
|
|
425
441
|
|
|
@@ -436,23 +452,26 @@ export class AgentHost {
|
|
|
436
452
|
this.client = createClient(AgentHostService, transport);
|
|
437
453
|
}
|
|
438
454
|
|
|
455
|
+
/** Executes a host tool using an agent protocol request message. */
|
|
439
456
|
async executeTool(
|
|
440
457
|
request: ExecuteAgentToolRequest,
|
|
441
458
|
): Promise<ExecuteAgentToolResponse> {
|
|
442
459
|
return await this.client.executeTool(request);
|
|
443
460
|
}
|
|
444
461
|
|
|
445
|
-
|
|
446
|
-
request: SearchAgentToolsRequest,
|
|
447
|
-
): Promise<SearchAgentToolsResponse> {
|
|
448
|
-
return await this.client.searchTools(request);
|
|
449
|
-
}
|
|
450
|
-
|
|
462
|
+
/** Lists host tools visible to the current agent request. */
|
|
451
463
|
async listTools(
|
|
452
464
|
request: ListAgentToolsRequest,
|
|
453
465
|
): Promise<ListAgentToolsResponse> {
|
|
454
466
|
return await this.client.listTools(request);
|
|
455
467
|
}
|
|
468
|
+
|
|
469
|
+
/** Resolves a configured agent connection for the current turn. */
|
|
470
|
+
async resolveConnection(
|
|
471
|
+
request: ResolveAgentConnectionRequest,
|
|
472
|
+
): Promise<ResolvedAgentConnection> {
|
|
473
|
+
return await this.client.resolveConnection(request);
|
|
474
|
+
}
|
|
456
475
|
}
|
|
457
476
|
|
|
458
477
|
function agentHostTransportOptions(rawTarget: string): {
|
|
@@ -506,6 +525,7 @@ function agentHostRelayTokenInterceptor(token: string): Interceptor {
|
|
|
506
525
|
};
|
|
507
526
|
}
|
|
508
527
|
|
|
528
|
+
/** Builds the Connect service implementation used by the TypeScript runtime. */
|
|
509
529
|
export function createAgentProviderService(
|
|
510
530
|
provider: AgentProvider,
|
|
511
531
|
): Partial<ServiceImpl<typeof AgentProviderService>> {
|
package/src/api.ts
CHANGED
|
@@ -26,6 +26,13 @@ export interface Access {
|
|
|
26
26
|
role: string;
|
|
27
27
|
}
|
|
28
28
|
|
|
29
|
+
/**
|
|
30
|
+
* Describes public host metadata available to provider code.
|
|
31
|
+
*/
|
|
32
|
+
export interface Host {
|
|
33
|
+
publicBaseUrl: string;
|
|
34
|
+
}
|
|
35
|
+
|
|
29
36
|
/**
|
|
30
37
|
* Request metadata forwarded to provider handlers by the Gestalt runtime.
|
|
31
38
|
*/
|
|
@@ -35,6 +42,7 @@ export interface Request {
|
|
|
35
42
|
subject: Subject;
|
|
36
43
|
credential: Credential;
|
|
37
44
|
access: Access;
|
|
45
|
+
host: Host;
|
|
38
46
|
idempotencyKey: string;
|
|
39
47
|
// Workflow callback metadata uses a JSON-style lowerCamelCase object such as
|
|
40
48
|
// runId, target.plugin.pluginName, trigger.scheduleId, and trigger.event.specVersion.
|
|
@@ -106,6 +114,7 @@ export function request(
|
|
|
106
114
|
workflow: Record<string, unknown> = {},
|
|
107
115
|
invocationToken = "",
|
|
108
116
|
idempotencyKey = "",
|
|
117
|
+
host: Partial<Host> = {},
|
|
109
118
|
): Request {
|
|
110
119
|
return {
|
|
111
120
|
token,
|
|
@@ -131,6 +140,9 @@ export function request(
|
|
|
131
140
|
workflow: {
|
|
132
141
|
...workflow,
|
|
133
142
|
},
|
|
143
|
+
host: {
|
|
144
|
+
publicBaseUrl: host.publicBaseUrl ?? "",
|
|
145
|
+
},
|
|
134
146
|
invocationToken,
|
|
135
147
|
idempotencyKey: idempotencyKey.trim(),
|
|
136
148
|
};
|
package/src/authorization.ts
CHANGED
|
@@ -21,7 +21,7 @@ import {
|
|
|
21
21
|
ReadRelationshipsRequestSchema,
|
|
22
22
|
ResourceSearchRequestSchema,
|
|
23
23
|
SubjectSearchRequestSchema,
|
|
24
|
-
} from "
|
|
24
|
+
} from "./internal/gen/v1/authorization_pb.ts";
|
|
25
25
|
|
|
26
26
|
/**
|
|
27
27
|
* Environment variable containing the Unix socket path or relay target for the
|
|
@@ -80,7 +80,8 @@ export class AuthorizationClient {
|
|
|
80
80
|
...(transportOptions.nodeOptions
|
|
81
81
|
? {
|
|
82
82
|
nodeOptions: {
|
|
83
|
-
createConnection: () =>
|
|
83
|
+
createConnection: () =>
|
|
84
|
+
connect({ path: transportOptions.nodeOptions!.path }),
|
|
84
85
|
},
|
|
85
86
|
}
|
|
86
87
|
: {}),
|
package/src/cache.ts
CHANGED
|
@@ -3,14 +3,17 @@ import { connect } from "node:net";
|
|
|
3
3
|
import { createClient, type Client, type Interceptor } from "@connectrpc/connect";
|
|
4
4
|
import { createGrpcTransport } from "@connectrpc/connect-node";
|
|
5
5
|
|
|
6
|
-
import { Cache as CacheService } from "
|
|
6
|
+
import { Cache as CacheService } from "./internal/gen/v1/cache_pb.ts";
|
|
7
7
|
import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
|
|
8
8
|
import type { MaybePromise } from "./api.ts";
|
|
9
9
|
|
|
10
|
+
/** Base environment variable for discovering cache runtime sockets. */
|
|
10
11
|
export const ENV_CACHE_SOCKET = "GESTALT_CACHE_SOCKET";
|
|
11
12
|
const CACHE_SOCKET_TOKEN_SUFFIX = "_TOKEN";
|
|
12
13
|
const CACHE_RELAY_TOKEN_HEADER = "x-gestalt-host-service-relay-token";
|
|
13
|
-
|
|
14
|
+
/** Base environment variable for the default cache relay token. */
|
|
15
|
+
export const ENV_CACHE_SOCKET_TOKEN =
|
|
16
|
+
`${ENV_CACHE_SOCKET}${CACHE_SOCKET_TOKEN_SUFFIX}`;
|
|
14
17
|
|
|
15
18
|
/**
|
|
16
19
|
* Single cache entry used by batch cache APIs.
|
|
@@ -136,7 +139,8 @@ export class Cache {
|
|
|
136
139
|
...(transportOptions.nodeOptions
|
|
137
140
|
? {
|
|
138
141
|
nodeOptions: {
|
|
139
|
-
createConnection: () =>
|
|
142
|
+
createConnection: () =>
|
|
143
|
+
connect({ path: transportOptions.nodeOptions!.path }),
|
|
140
144
|
},
|
|
141
145
|
}
|
|
142
146
|
: {}),
|
|
@@ -145,6 +149,7 @@ export class Cache {
|
|
|
145
149
|
this.client = createClient(CacheService, transport);
|
|
146
150
|
}
|
|
147
151
|
|
|
152
|
+
/** Returns a cached value, or `undefined` when the key is missing. */
|
|
148
153
|
async get(key: string): Promise<Uint8Array | undefined> {
|
|
149
154
|
const response = await this.client.get({
|
|
150
155
|
key,
|
|
@@ -155,6 +160,7 @@ export class Cache {
|
|
|
155
160
|
return cloneBytes(response.value);
|
|
156
161
|
}
|
|
157
162
|
|
|
163
|
+
/** Returns the subset of requested keys that currently exist. */
|
|
158
164
|
async getMany(keys: string[]): Promise<Record<string, Uint8Array>> {
|
|
159
165
|
const response = await this.client.getMany({
|
|
160
166
|
keys: [...keys],
|
|
@@ -162,6 +168,7 @@ export class Cache {
|
|
|
162
168
|
return entriesToRecord(response.entries);
|
|
163
169
|
}
|
|
164
170
|
|
|
171
|
+
/** Stores a cached value with an optional TTL. */
|
|
165
172
|
async set(
|
|
166
173
|
key: string,
|
|
167
174
|
value: Uint8Array,
|
|
@@ -175,6 +182,7 @@ export class Cache {
|
|
|
175
182
|
});
|
|
176
183
|
}
|
|
177
184
|
|
|
185
|
+
/** Stores multiple values with an optional shared TTL. */
|
|
178
186
|
async setMany(
|
|
179
187
|
entries: Iterable<CacheEntry>,
|
|
180
188
|
options?: CacheSetOptions,
|
|
@@ -186,6 +194,7 @@ export class Cache {
|
|
|
186
194
|
});
|
|
187
195
|
}
|
|
188
196
|
|
|
197
|
+
/** Deletes a cached value and reports whether it existed. */
|
|
189
198
|
async delete(key: string): Promise<boolean> {
|
|
190
199
|
const response = await this.client.delete({
|
|
191
200
|
key,
|
|
@@ -193,6 +202,7 @@ export class Cache {
|
|
|
193
202
|
return response.deleted;
|
|
194
203
|
}
|
|
195
204
|
|
|
205
|
+
/** Deletes several cached values and returns the number removed. */
|
|
196
206
|
async deleteMany(keys: string[]): Promise<number | bigint> {
|
|
197
207
|
const response = await this.client.deleteMany({
|
|
198
208
|
keys: [...keys],
|
|
@@ -200,6 +210,7 @@ export class Cache {
|
|
|
200
210
|
return toJsInt(response.deleted);
|
|
201
211
|
}
|
|
202
212
|
|
|
213
|
+
/** Refreshes the TTL for an existing key. */
|
|
203
214
|
async touch(key: string, ttlMs: number): Promise<boolean> {
|
|
204
215
|
const ttl = toProtoDuration(ttlMs);
|
|
205
216
|
const response = await this.client.touch({
|
package/src/http-subject.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { Access, Credential, MaybePromise, Subject } from "./api.ts";
|
|
1
|
+
import type { Access, Credential, Host, MaybePromise, Subject } from "./api.ts";
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
4
|
* Verified hosted HTTP request metadata passed into optional plugin-local
|
|
@@ -26,6 +26,7 @@ export interface HTTPSubjectResolutionContext {
|
|
|
26
26
|
subject: Subject;
|
|
27
27
|
credential: Credential;
|
|
28
28
|
access: Access;
|
|
29
|
+
host: Host;
|
|
29
30
|
workflow: Record<string, unknown>;
|
|
30
31
|
}
|
|
31
32
|
|
|
@@ -96,6 +97,9 @@ export function cloneHTTPSubjectResolutionContext(
|
|
|
96
97
|
access: {
|
|
97
98
|
...input.access,
|
|
98
99
|
},
|
|
100
|
+
host: {
|
|
101
|
+
...input.host,
|
|
102
|
+
},
|
|
99
103
|
workflow: {
|
|
100
104
|
...input.workflow,
|
|
101
105
|
},
|