@valon-technologies/gestalt 0.0.1-alpha.14 → 0.0.1-alpha.17

package/README.md

@@ -1,110 +1,90 @@
 # Gestalt TypeScript SDK
 
-This package provides the TypeScript authoring surface for executable Gestalt
-providers.
+Use the TypeScript SDK to build Bun-based executable Gestalt providers with
+explicit runtime schemas.
 
-It is intended for source providers discovered through `package.json` and for
-packaged providers built from that same source tree.
+The package is published as `@valon-technologies/gestalt`.
 
-## Provider target
-
-Point the package at the provider module with a top-level `gestalt.provider`
-property in `package.json`:
-
-```json
-{
-  "name": "my-provider",
-  "version": "0.0.1-alpha.1",
-  "dependencies": {
-    "@valon-technologies/gestalt": "0.0.1-alpha.13"
-  },
-  "gestalt": {
-    "provider": {
-      "kind": "plugin",
-      "target": "./provider.ts#plugin"
-    }
-  }
-}
+```sh
+bun add @valon-technologies/gestalt@0.0.1-alpha.16
 ```
 
-The target is a relative file path with an optional export suffix. The runtime
-accepts:
-
-- `gestalt.provider` as `{ "kind": "...", "target": "./file.ts#export" }`
-- `gestalt.provider` as a string like `"plugin:./provider.ts#plugin"` or `"cache:./cache.ts#provider"`
-
-Use `"plugin"` as the kind token for executable plugin providers.
-
-If the export suffix is omitted, the runtime looks for `provider`, then
-`plugin`, then the default export.
-
-## Authoring
-
-Use explicit runtime schemas to define plugin operation inputs and outputs:
-
 ```ts
-import {
-  definePlugin,
-  ok,
-  operation,
-  response,
-  s,
-} from "@valon-technologies/gestalt";
+import { definePlugin, ok, operation, s } from "@valon-technologies/gestalt";
 
 export const plugin = definePlugin({
-  displayName: "Example Provider",
-  description: "A provider implemented with the Gestalt TypeScript SDK",
-  configure(name, config) {
-    console.log("configured", name, config);
-  },
-  sessionCatalog(request) {
-    return {
-      name: "example-session",
-      operations: [
-        {
-          id: "session-ping",
-          method: "GET",
-        },
-      ],
-    };
-  },
+  displayName: "Search",
   operations: [
     operation({
-      id: "greet",
+      id: "search",
       method: "GET",
       readOnly: true,
       input: s.object({
-        name: s.string({ description: "Name to greet", default: "World" }),
-        excited: s.optional(s.boolean()),
+        query: s.string({ description: "Search query" }),
+        limit: s.integer({ description: "Maximum results", default: 10 }),
       }),
       output: s.object({
-        message: s.string(),
+        results: s.array(s.string()),
       }),
       async handler(input) {
-        return ok({
-          message: `Hello, ${input.name}${input.excited ? "!" : "."}`,
-        });
+        return ok({ results: [input.query].slice(0, input.limit) });
       },
     }),
   ],
 });
 ```
 
-Use `ok(body)` for normal responses and `response(status, body)` when a handler
-needs to set a non-200 status. Plain objects with `status` and `body` fields
-are treated as user data.
+## Provider target
 
-Authentication providers, cache providers, and secrets providers use dedicated helpers:
+Point the package at the provider module with a top-level `gestalt.provider`
+property in `package.json`.
 
-```ts
-import {
-  Cache,
-  defineAuthenticationProvider,
-  defineCacheProvider,
-  defineSecretsProvider,
-} from "@valon-technologies/gestalt";
+```json
+{
+  "name": "my-provider",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@valon-technologies/gestalt": "0.0.1-alpha.16"
+  },
+  "gestalt": {
+    "provider": {
+      "kind": "plugin",
+      "target": "./provider.ts#plugin"
+    }
+  }
+}
 ```
 
+The target is a relative file path with an optional export suffix. If the suffix
+is omitted, the runtime looks for `provider`, then `plugin`, then the default
+export.
+
+Use `"plugin"` as the kind token for executable plugin providers. Use an object
+target with an explicit kind for authentication, authorization, cache,
+IndexedDB, S3, secrets, workflow, agent, and hosted-runtime providers.
+
+## Public surface
+
+The root package exports provider definition helpers:
+
+- `definePlugin` for integration operations and session catalogs.
+- `defineAuthenticationProvider` and `defineAuthorizationProvider` for auth
+  surfaces.
+- `defineCacheProvider`, `defineIndexedDBProvider`, `defineS3Provider`, and
+  `defineSecretsProvider` for host-service backends.
+- `defineWorkflowProvider`, `defineAgentProvider`, and
+  `definePluginRuntimeProvider` for workflow, agent, and hosted-runtime
+  backends.
+- `s` schema builders for operation input, output, and catalog metadata.
+- Host-service clients for cache, IndexedDB, S3, workflows, agents,
+  invocations, and telemetry.
+
+TypeScript types are not enough to describe runtime payloads. Use the schema
+builders for every operation input and output that should appear in the
+Gestalt catalog.
+
 ## Runtime and build entrypoints
 
 Source-mode runtime:
@@ -116,7 +96,7 @@ gestalt-ts-runtime ROOT plugin:./provider.ts#plugin
 Release build:
 
 ```sh
-gestalt-ts-build ROOT cache:./cache.ts#provider OUTPUT PROVIDER_NAME GOOS GOARCH
+gestalt-ts-build ROOT plugin:./provider.ts#plugin OUTPUT PROVIDER_NAME GOOS GOARCH
 ```
 
 The build entrypoint compiles a standalone executable with Bun and bundles the
@@ -130,6 +110,15 @@ From the repo root:
 buf generate --template sdk/proto/buf.typescript.gen.yaml sdk/proto
 ```
 
+## API reference
+
+The TypeDoc reference is generated from the authored public surface plus
+entrypoint shims under `docs/entrypoints`.
+
+```sh
+bun run docs:build
+```
+
 ## Local checks
 
 From `sdk/typescript`:
@@ -139,4 +128,5 @@ export PATH="$HOME/.bun/bin:$PATH"
 bun install
 bun run build:proto
 bun run check
+bun run docs:check
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valon-technologies/gestalt",
-  "version": "0.0.1-alpha.14",
+  "version": "0.0.1-alpha.17",
   "description": "TypeScript SDK for Gestalt executable providers",
   "type": "module",
   "repository": {
@@ -12,6 +12,7 @@
     "./build": "./src/build.ts",
     "./runtime": "./src/runtime.ts",
     "./schema": "./src/schema.ts",
+    "./test/agent-contract": "./src/test-agent-contract.ts",
     "./telemetry": "./src/telemetry.ts",
     "./target": "./src/target.ts"
   },
@@ -21,7 +22,6 @@
   },
   "files": [
     "src",
-    "gen",
     "README.md",
     "tsconfig.json"
   ],

package/src/agent-manager.ts

@@ -23,47 +23,67 @@ import {
   type AgentSession,
   type AgentTurn,
   type AgentTurnEvent,
-} from "../gen/v1/agent_pb.ts";
+} from "./internal/gen/v1/agent_pb.ts";
 import type { Request } from "./api.ts";
 
+/** Environment variable containing the agent-manager host-service target. */
 export const ENV_AGENT_MANAGER_SOCKET = "GESTALT_AGENT_MANAGER_SOCKET";
-export const ENV_AGENT_MANAGER_SOCKET_TOKEN = `${ENV_AGENT_MANAGER_SOCKET}_TOKEN`;
+/** Environment variable containing the optional agent-manager relay token. */
+export const ENV_AGENT_MANAGER_SOCKET_TOKEN =
+  `${ENV_AGENT_MANAGER_SOCKET}_TOKEN`;
 const AGENT_MANAGER_RELAY_TOKEN_HEADER = "x-gestalt-host-service-relay-token";
 
+/** Shape accepted when creating an agent session through the host manager. */
 export type AgentManagerCreateSessionInput = MessageInitShape<
   typeof AgentManagerCreateSessionRequestSchema
 >;
+/** Shape accepted when fetching an agent session through the host manager. */
 export type AgentManagerGetSessionInput = MessageInitShape<
   typeof AgentManagerGetSessionRequestSchema
 >;
+/** Shape accepted when listing agent sessions through the host manager. */
 export type AgentManagerListSessionsInput = MessageInitShape<
   typeof AgentManagerListSessionsRequestSchema
 >;
+/** Shape accepted when updating an agent session through the host manager. */
 export type AgentManagerUpdateSessionInput = MessageInitShape<
   typeof AgentManagerUpdateSessionRequestSchema
 >;
+/** Shape accepted when creating an agent turn through the host manager. */
 export type AgentManagerCreateTurnInput = MessageInitShape<
   typeof AgentManagerCreateTurnRequestSchema
 >;
+/** Shape accepted when fetching an agent turn through the host manager. */
 export type AgentManagerGetTurnInput = MessageInitShape<
   typeof AgentManagerGetTurnRequestSchema
 >;
+/** Shape accepted when listing agent turns through the host manager. */
 export type AgentManagerListTurnsInput = MessageInitShape<
   typeof AgentManagerListTurnsRequestSchema
 >;
+/** Shape accepted when cancelling an agent turn through the host manager. */
 export type AgentManagerCancelTurnInput = MessageInitShape<
   typeof AgentManagerCancelTurnRequestSchema
 >;
+/** Shape accepted when listing events for an agent turn. */
 export type AgentManagerListTurnEventsInput = MessageInitShape<
   typeof AgentManagerListTurnEventsRequestSchema
 >;
+/** Shape accepted when listing agent interactions. */
 export type AgentManagerListInteractionsInput = MessageInitShape<
   typeof AgentManagerListInteractionsRequestSchema
 >;
+/** Shape accepted when resolving an agent interaction. */
 export type AgentManagerResolveInteractionInput = MessageInitShape<
   typeof AgentManagerResolveInteractionRequestSchema
 >;
 
+/**
+ * Client for managing agent sessions, turns, events, and interactions.
+ *
+ * The constructor accepts either a Gestalt request or an invocation token. Each
+ * manager call forwards that token to the host service.
+ */
 export class AgentManager {
   private readonly client: Client<typeof AgentManagerHostService>;
   private readonly invocationToken: string;
@@ -89,6 +109,7 @@ export class AgentManager {
     this.client = createClient(AgentManagerHostService, transport);
   }
 
+  /** Creates an agent session. */
   async createSession(
     request: AgentManagerCreateSessionInput,
   ): Promise<AgentSession> {
@@ -98,6 +119,7 @@ export class AgentManager {
     });
   }
 
+  /** Fetches one agent session. */
   async getSession(request: AgentManagerGetSessionInput): Promise<AgentSession> {
     return await this.client.getSession({
       ...request,
@@ -105,6 +127,7 @@ export class AgentManager {
     });
   }
 
+  /** Lists agent sessions visible to the invocation token. */
   async listSessions(
     request: AgentManagerListSessionsInput = {},
   ): Promise<AgentSession[]> {
@@ -115,6 +138,7 @@ export class AgentManager {
     return [...response.sessions];
   }
 
+  /** Updates mutable fields on an agent session. */
   async updateSession(
     request: AgentManagerUpdateSessionInput,
   ): Promise<AgentSession> {
@@ -124,6 +148,7 @@ export class AgentManager {
     });
   }
 
+  /** Creates an agent turn. */
   async createTurn(request: AgentManagerCreateTurnInput): Promise<AgentTurn> {
     return await this.client.createTurn({
       ...request,
@@ -131,6 +156,7 @@ export class AgentManager {
     });
   }
 
+  /** Fetches one agent turn. */
   async getTurn(request: AgentManagerGetTurnInput): Promise<AgentTurn> {
     return await this.client.getTurn({
       ...request,
@@ -138,6 +164,7 @@ export class AgentManager {
     });
   }
 
+  /** Lists turns for an agent session. */
   async listTurns(request: AgentManagerListTurnsInput): Promise<AgentTurn[]> {
     const response = await this.client.listTurns({
       ...request,
@@ -146,6 +173,7 @@ export class AgentManager {
     return [...response.turns];
   }
 
+  /** Cancels an in-progress agent turn. */
   async cancelTurn(request: AgentManagerCancelTurnInput): Promise<AgentTurn> {
     return await this.client.cancelTurn({
       ...request,
@@ -153,6 +181,7 @@ export class AgentManager {
     });
   }
 
+  /** Lists events emitted for an agent turn. */
   async listTurnEvents(
     request: AgentManagerListTurnEventsInput,
   ): Promise<AgentTurnEvent[]> {
@@ -163,6 +192,7 @@ export class AgentManager {
     return [...response.events];
   }
 
+  /** Lists pending or completed agent interactions. */
   async listInteractions(
     request: AgentManagerListInteractionsInput,
   ): Promise<AgentInteraction[]> {
@@ -173,6 +203,7 @@ export class AgentManager {
     return [...response.interactions];
   }
 
+  /** Resolves an agent interaction with a host response. */
   async resolveInteraction(
     request: AgentManagerResolveInteractionInput,
   ): Promise<AgentInteraction> {

package/src/agent.ts

@@ -67,17 +67,23 @@ import {
   type ListedAgentTool,
   type ResolveAgentProviderInteractionRequest,
   type ResolvedAgentTool,
-  type SearchAgentToolsRequest,
-  type SearchAgentToolsResponse,
   type UpdateAgentProviderSessionRequest,
-} from "../gen/v1/agent_pb.ts";
+} from "./internal/gen/v1/agent_pb.ts";
 import { errorMessage, type MaybePromise } from "./api.ts";
 import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
 
+/** Environment variable containing the agent-host service target. */
 export const ENV_AGENT_HOST_SOCKET = "GESTALT_AGENT_HOST_SOCKET";
+/** Environment variable containing the optional agent-host relay token. */
 export const ENV_AGENT_HOST_SOCKET_TOKEN = `${ENV_AGENT_HOST_SOCKET}_TOKEN`;
 const AGENT_HOST_RELAY_TOKEN_HEADER = "x-gestalt-host-service-relay-token";
 
+/**
+ * Generated agent protocol message types commonly used by authored providers.
+ *
+ * These are re-exported so provider code can type sessions, turns, messages,
+ * interactions, and host-tool requests without importing from `gen`.
+ */
 export type {
   AgentActor,
   AgentInteraction,
@@ -110,8 +116,6 @@ export type {
   ListedAgentTool,
   ResolveAgentProviderInteractionRequest,
   ResolvedAgentTool,
-  SearchAgentToolsRequest,
-  SearchAgentToolsResponse,
   UpdateAgentProviderSessionRequest,
 };
 export {
@@ -123,11 +127,13 @@ export {
   AgentToolSourceMode,
 };
 
+/** JSON-like value accepted for an agent turn display payload. */
 export type AgentTurnDisplayValue =
   | JsonValue
   | Value
   | MessageInitShape<typeof ValueSchema>;
 
+/** Initializer for a turn display with JSON-like input/output/error fields. */
 export type AgentTurnDisplayInit = Omit<
   MessageInitShape<typeof AgentTurnDisplaySchema>,
   "$typeName" | "input" | "output" | "error"
@@ -137,6 +143,7 @@ export type AgentTurnDisplayInit = Omit<
   error?: AgentTurnDisplayValue | undefined;
 };
 
+/** Initializer for a turn event with authored display payload helpers. */
 export type AgentTurnEventInit = Omit<
   MessageInitShape<typeof AgentTurnEventSchema>,
   "$typeName" | "display"
@@ -144,6 +151,7 @@ export type AgentTurnEventInit = Omit<
   display?: AgentTurnDisplayInit | undefined;
 };
 
+/** Handlers and runtime metadata for an agent provider. */
 export interface AgentProviderOptions extends RuntimeProviderOptions {
   createSession?: (
     request: CreateAgentProviderSessionRequest,
@@ -186,6 +194,7 @@ export interface AgentProviderOptions extends RuntimeProviderOptions {
   ) => MaybePromise<MessageInitShape<typeof AgentProviderCapabilitiesSchema>>;
 }
 
+/** Runtime provider implementation for the Gestalt agent host contract. */
 export class AgentProvider extends RuntimeProvider {
   readonly kind = "agent" as const;
 
@@ -354,6 +363,7 @@ export class AgentProvider extends RuntimeProvider {
   }
 }
 
+/** Creates an agent provider for export from a provider module. */
 export function defineAgentProvider(options: AgentProviderOptions): AgentProvider {
   return new AgentProvider(options);
 }
@@ -408,6 +418,7 @@ function isValueInit(value: unknown): value is MessageInitShape<typeof ValueSche
   );
 }
 
+/** Runtime type guard for agent providers loaded from user modules. */
 export function isAgentProvider(value: unknown): value is AgentProvider {
   return (
     value instanceof AgentProvider ||
@@ -420,6 +431,7 @@ export function isAgentProvider(value: unknown): value is AgentProvider {
   );
 }
 
+/** Client for the agent host service available inside agent providers. */
 export class AgentHost {
   private readonly client: Client<typeof AgentHostService>;
 
@@ -436,18 +448,14 @@ export class AgentHost {
     this.client = createClient(AgentHostService, transport);
   }
 
+  /** Executes a host tool using an agent protocol request message. */
   async executeTool(
     request: ExecuteAgentToolRequest,
   ): Promise<ExecuteAgentToolResponse> {
     return await this.client.executeTool(request);
   }
 
-  async searchTools(
-    request: SearchAgentToolsRequest,
-  ): Promise<SearchAgentToolsResponse> {
-    return await this.client.searchTools(request);
-  }
-
+  /** Lists host tools visible to the current agent request. */
   async listTools(
     request: ListAgentToolsRequest,
   ): Promise<ListAgentToolsResponse> {
@@ -506,6 +514,7 @@ function agentHostRelayTokenInterceptor(token: string): Interceptor {
   };
 }
 
+/** Builds the Connect service implementation used by the TypeScript runtime. */
 export function createAgentProviderService(
   provider: AgentProvider,
 ): Partial<ServiceImpl<typeof AgentProviderService>> {

package/src/authorization.ts

@@ -21,7 +21,7 @@ import {
   ReadRelationshipsRequestSchema,
   ResourceSearchRequestSchema,
   SubjectSearchRequestSchema,
-} from "../gen/v1/authorization_pb.ts";
+} from "./internal/gen/v1/authorization_pb.ts";
 
 /**
  * Environment variable containing the Unix socket path or relay target for the

package/src/build.ts

@@ -1,3 +1,5 @@
+#!/usr/bin/env bun
+
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";

package/src/cache.ts

@@ -3,14 +3,17 @@ import { connect } from "node:net";
 import { createClient, type Client, type Interceptor } from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
 
-import { Cache as CacheService } from "../gen/v1/cache_pb.ts";
+import { Cache as CacheService } from "./internal/gen/v1/cache_pb.ts";
 import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
 import type { MaybePromise } from "./api.ts";
 
+/** Base environment variable for discovering cache runtime sockets. */
 export const ENV_CACHE_SOCKET = "GESTALT_CACHE_SOCKET";
 const CACHE_SOCKET_TOKEN_SUFFIX = "_TOKEN";
 const CACHE_RELAY_TOKEN_HEADER = "x-gestalt-host-service-relay-token";
-export const ENV_CACHE_SOCKET_TOKEN = `${ENV_CACHE_SOCKET}${CACHE_SOCKET_TOKEN_SUFFIX}`;
+/** Base environment variable for the default cache relay token. */
+export const ENV_CACHE_SOCKET_TOKEN =
+  `${ENV_CACHE_SOCKET}${CACHE_SOCKET_TOKEN_SUFFIX}`;
 
 /**
  * Single cache entry used by batch cache APIs.
@@ -145,6 +148,7 @@ export class Cache {
     this.client = createClient(CacheService, transport);
   }
 
+  /** Returns a cached value, or `undefined` when the key is missing. */
   async get(key: string): Promise<Uint8Array | undefined> {
     const response = await this.client.get({
       key,
@@ -155,6 +159,7 @@ export class Cache {
     return cloneBytes(response.value);
   }
 
+  /** Returns the subset of requested keys that currently exist. */
   async getMany(keys: string[]): Promise<Record<string, Uint8Array>> {
     const response = await this.client.getMany({
       keys: [...keys],
@@ -162,6 +167,7 @@ export class Cache {
     return entriesToRecord(response.entries);
   }
 
+  /** Stores a cached value with an optional TTL. */
   async set(
     key: string,
     value: Uint8Array,
@@ -175,6 +181,7 @@ export class Cache {
     });
   }
 
+  /** Stores multiple values with an optional shared TTL. */
   async setMany(
     entries: Iterable<CacheEntry>,
     options?: CacheSetOptions,
@@ -186,6 +193,7 @@ export class Cache {
     });
   }
 
+  /** Deletes a cached value and reports whether it existed. */
   async delete(key: string): Promise<boolean> {
     const response = await this.client.delete({
       key,
@@ -193,6 +201,7 @@ export class Cache {
     return response.deleted;
   }
 
+  /** Deletes several cached values and returns the number removed. */
   async deleteMany(keys: string[]): Promise<number | bigint> {
     const response = await this.client.deleteMany({
       keys: [...keys],
@@ -200,6 +209,7 @@ export class Cache {
     return toJsInt(response.deleted);
   }
 
+  /** Refreshes the TTL for an existing key. */
   async touch(key: string, ttlMs: number): Promise<boolean> {
     const ttl = toProtoDuration(ttlMs);
     const response = await this.client.touch({

package/src/index.ts

@@ -201,16 +201,13 @@ export {
 } from "./provider.ts";
 export {
   PluginRuntimeEgressMode,
-  PluginRuntimeHostServiceAccess,
   PluginRuntimeProvider,
   createPluginRuntimeProviderService,
   definePluginRuntimeProvider,
   isPluginRuntimeProvider,
-  type BindPluginRuntimeHostServiceRequest,
   type GetPluginRuntimeSessionRequest,
   type HostedPlugin,
   type ListPluginRuntimeSessionsRequest,
-  type PluginRuntimeHostServiceBinding,
   type PluginRuntimeProviderOptions,
   type PluginRuntimeSession,
   type PluginRuntimeSupport,
@@ -368,8 +365,6 @@ export {
   type ListedAgentTool,
   type ResolveAgentProviderInteractionRequest,
   type ResolvedAgentTool,
-  type SearchAgentToolsRequest,
-  type SearchAgentToolsResponse,
   type UpdateAgentProviderSessionRequest,
 } from "./agent.ts";
 export {

package/src/indexeddb.ts

@@ -7,7 +7,7 @@ import {
   CursorDirection as ProtoCursorDirection,
   TransactionMode as ProtoTransactionMode,
   TransactionDurabilityHint as ProtoTransactionDurabilityHint,
-} from "../gen/v1/datastore_pb";
+} from "./internal/gen/v1/datastore_pb";
 
 const ENV_INDEXEDDB_SOCKET = "GESTALT_INDEXEDDB_SOCKET";
 const INDEXEDDB_SOCKET_TOKEN_SUFFIX = "_TOKEN";