@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 CHANGED
@@ -1,110 +1,90 @@
1
1
  # Gestalt TypeScript SDK
2
2
 
3
- This package provides the TypeScript authoring surface for executable Gestalt
4
- providers.
3
+ Use the TypeScript SDK to build Bun-based executable Gestalt providers with
4
+ explicit runtime schemas.
5
5
 
6
- It is intended for source providers discovered through `package.json` and for
7
- packaged providers built from that same source tree.
6
+ The package is published as `@valon-technologies/gestalt`.
8
7
 
9
- ## Provider target
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: "Example Provider",
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: "greet",
19
+ id: "search",
74
20
  method: "GET",
75
21
  readOnly: true,
76
22
  input: s.object({
77
- name: s.string({ description: "Name to greet", default: "World" }),
78
- excited: s.optional(s.boolean()),
23
+ query: s.string({ description: "Search query" }),
24
+ limit: s.integer({ description: "Maximum results", default: 10 }),
79
25
  }),
80
26
  output: s.object({
81
- message: s.string(),
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
- Use `ok(body)` for normal responses and `response(status, body)` when a handler
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
- Authentication providers, cache providers, and secrets providers use dedicated helpers:
39
+ Point the package at the provider module with a top-level `gestalt.provider`
40
+ property in `package.json`.
98
41
 
99
- ```ts
100
- import {
101
- Cache,
102
- defineAuthenticationProvider,
103
- defineCacheProvider,
104
- defineSecretsProvider,
105
- } from "@valon-technologies/gestalt";
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 cache:./cache.ts#provider OUTPUT PROVIDER_NAME GOOS GOARCH
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.16",
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
  ],
@@ -23,47 +23,67 @@ import {
23
23
  type AgentSession,
24
24
  type AgentTurn,
25
25
  type AgentTurnEvent,
26
- } from "../gen/v1/agent_pb.ts";
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
- export const ENV_AGENT_MANAGER_SOCKET_TOKEN = `${ENV_AGENT_MANAGER_SOCKET}_TOKEN`;
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 "../gen/v1/agent_pb.ts";
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
- async searchTools(
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
  };
@@ -21,7 +21,7 @@ import {
21
21
  ReadRelationshipsRequestSchema,
22
22
  ResourceSearchRequestSchema,
23
23
  SubjectSearchRequestSchema,
24
- } from "../gen/v1/authorization_pb.ts";
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: () => connect(transportOptions.nodeOptions!.path),
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 "../gen/v1/cache_pb.ts";
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
- export const ENV_CACHE_SOCKET_TOKEN = `${ENV_CACHE_SOCKET}${CACHE_SOCKET_TOKEN_SUFFIX}`;
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: () => connect(transportOptions.nodeOptions!.path),
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({
@@ -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
  },