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

package/src/runtime.ts

@@ -1,3 +1,5 @@
+#!/usr/bin/env bun
+
 import { rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http2";
 import { dirname, resolve } from "node:path";
@@ -14,7 +16,7 @@ import { connectNodeAdapter } from "@connectrpc/connect-node";
 
 import {
   AgentProvider as AgentProviderService,
-} from "../gen/v1/agent_pb.ts";
+} from "./internal/gen/v1/agent_pb.ts";
 import {
   AuthenticationProvider as AuthenticationProviderService,
   AuthSessionSettingsSchema,
@@ -22,7 +24,7 @@ import {
   BeginLoginResponseSchema,
   type CompleteLoginRequest as AuthCompleteLoginRequest,
   type ValidateExternalTokenRequest,
-} from "../gen/v1/authentication_pb.ts";
+} from "./internal/gen/v1/authentication_pb.ts";
 import {
   Cache as CacheService,
   CacheDeleteManyResponseSchema,
@@ -31,12 +33,12 @@ import {
   CacheGetResponseSchema,
   CacheResultSchema,
   CacheTouchResponseSchema,
-} from "../gen/v1/cache_pb.ts";
+} from "./internal/gen/v1/cache_pb.ts";
 import {
   SecretsProvider as SecretsProviderService,
   GetSecretResponseSchema,
   type GetSecretRequest,
-} from "../gen/v1/secrets_pb.ts";
+} from "./internal/gen/v1/secrets_pb.ts";
 import {
   CatalogOperationSchema as ProtoCatalogOperationSchema,
   CatalogParameterSchema as ProtoCatalogParameterSchema,
@@ -56,10 +58,10 @@ import {
   type ExecuteRequest,
   type GetSessionCatalogRequest,
   type StartProviderRequest,
-} from "../gen/v1/plugin_pb.ts";
+} from "./internal/gen/v1/plugin_pb.ts";
 import {
   PluginRuntimeProvider as PluginRuntimeProviderService,
-} from "../gen/v1/pluginruntime_pb.ts";
+} from "./internal/gen/v1/pluginruntime_pb.ts";
 import {
   ConfigureProviderResponseSchema,
   HealthCheckResponseSchema,
@@ -68,9 +70,9 @@ import {
   ProviderLifecycle,
   StartRuntimeProviderResponseSchema,
   type ConfigureProviderRequest,
-} from "../gen/v1/runtime_pb.ts";
-import { S3 as S3Service } from "../gen/v1/s3_pb.ts";
-import { WorkflowProvider as WorkflowProviderService } from "../gen/v1/workflow_pb.ts";
+} from "./internal/gen/v1/runtime_pb.ts";
+import { S3 as S3Service } from "./internal/gen/v1/s3_pb.ts";
+import { WorkflowProvider as WorkflowProviderService } from "./internal/gen/v1/workflow_pb.ts";
 import { errorMessage, type Request } from "./api.ts";
 import {
   AgentProvider,

package/src/s3.ts

@@ -26,14 +26,17 @@ import {
   type S3ObjectMeta as ProtoS3ObjectMeta,
   type S3ObjectRef as ProtoS3ObjectRef,
   WriteObjectResponseSchema,
-} from "../gen/v1/s3_pb.ts";
+} from "./internal/gen/v1/s3_pb.ts";
 import { errorMessage, type MaybePromise } from "./api.ts";
 import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
 
+/** Base environment variable for discovering S3 runtime sockets. */
 export const ENV_S3_SOCKET = "GESTALT_S3_SOCKET";
 const S3_SOCKET_TOKEN_SUFFIX = "_TOKEN";
 const S3_RELAY_TOKEN_HEADER = "x-gestalt-host-service-relay-token";
-export const ENV_S3_SOCKET_TOKEN = `${ENV_S3_SOCKET}${S3_SOCKET_TOKEN_SUFFIX}`;
+/** Base environment variable for the default S3 relay token. */
+export const ENV_S3_SOCKET_TOKEN =
+  `${ENV_S3_SOCKET}${S3_SOCKET_TOKEN_SUFFIX}`;
 const WRITE_CHUNK_SIZE = 64 * 1024;
 const textEncoder = new TextEncoder();
 
@@ -288,14 +291,20 @@ export class S3Provider extends RuntimeProvider {
     this.presignObjectHandler = options.presignObject;
   }
 
+  /** Fetches object metadata without reading the object body. */
   async headObject(ref: ObjectRef): Promise<ObjectMeta> {
     return await this.headObjectHandler(ref);
   }
 
-  async readObject(ref: ObjectRef, options?: ReadOptions): Promise<ProviderReadResult> {
+  /** Reads an object body from the provider implementation. */
+  async readObject(
+    ref: ObjectRef,
+    options?: ReadOptions,
+  ): Promise<ProviderReadResult> {
     return await this.readObjectHandler(ref, options);
   }
 
+  /** Writes an object body through the provider implementation. */
   async writeObject(
     ref: ObjectRef,
     body: AsyncIterable<Uint8Array>,
@@ -304,14 +313,17 @@ export class S3Provider extends RuntimeProvider {
     return await this.writeObjectHandler(ref, body, options);
   }
 
+  /** Deletes an object from the provider implementation. */
   async deleteObject(ref: ObjectRef): Promise<void> {
     await this.deleteObjectHandler(ref);
   }
 
+  /** Lists objects from the provider implementation. */
   async listObjects(options: ListOptions): Promise<ListPage> {
     return await this.listObjectsHandler(options);
   }
 
+  /** Copies an object in the provider implementation. */
   async copyObject(
     source: ObjectRef,
     destination: ObjectRef,
@@ -320,7 +332,11 @@ export class S3Provider extends RuntimeProvider {
     return await this.copyObjectHandler(source, destination, options);
   }
 
-  async presignObject(ref: ObjectRef, options?: PresignOptions): Promise<PresignResult> {
+  /** Generates a presigned URL from the provider implementation. */
+  async presignObject(
+    ref: ObjectRef,
+    options?: PresignOptions,
+  ): Promise<PresignResult> {
     return await this.presignObjectHandler(ref, options);
   }
 }
@@ -555,14 +571,17 @@ export class S3 {
     this.client = createClient(S3Service, transport);
   }
 
+  /** Returns a convenience helper for the latest version of an object. */
   object(bucket: string, key: string): S3Object {
     return new S3Object(this, { bucket, key });
   }
 
+  /** Returns a convenience helper pinned to a specific object version. */
   objectVersion(bucket: string, key: string, versionId: string): S3Object {
     return new S3Object(this, { bucket, key, versionId });
   }
 
+  /** Fetches object metadata without reading the object body. */
   async headObject(ref: ObjectRef): Promise<ObjectMeta> {
     const response = await s3Rpc(() =>
       this.client.headObject({
@@ -572,6 +591,7 @@ export class S3 {
     return fromProtoObjectMeta(response.meta);
   }
 
+  /** Opens a streaming read for an object. */
   async readObject(ref: ObjectRef, options?: ReadOptions): Promise<ReadResult> {
     const response = this.client.readObject({
       ref: toProtoObjectRef(ref),
@@ -588,6 +608,7 @@ export class S3 {
     };
   }
 
+  /** Writes an object body and returns the resulting metadata. */
   async writeObject(
     ref: ObjectRef,
     body?: S3BodySource,
@@ -601,6 +622,7 @@ export class S3 {
     return fromProtoObjectMeta(response.meta);
   }
 
+  /** Deletes an object. */
   async deleteObject(ref: ObjectRef): Promise<void> {
     await s3Rpc(() =>
       this.client.deleteObject({
@@ -609,6 +631,7 @@ export class S3 {
     );
   }
 
+  /** Lists objects within a bucket. */
   async listObjects(options: ListOptions): Promise<ListPage> {
     const response = await s3Rpc(() =>
       this.client.listObjects({
@@ -628,6 +651,7 @@ export class S3 {
     };
   }
 
+  /** Copies an object and returns metadata for the destination. */
   async copyObject(
     source: ObjectRef,
     destination: ObjectRef,
@@ -644,7 +668,11 @@ export class S3 {
     return fromProtoObjectMeta(response.meta);
   }
 
-  async presignObject(ref: ObjectRef, options?: PresignOptions): Promise<PresignResult> {
+  /** Generates a presigned URL for an object operation. */
+  async presignObject(
+    ref: ObjectRef,
+    options?: PresignOptions,
+  ): Promise<PresignResult> {
     const requestedMethod = options?.method ?? PresignMethod.Get;
     const response = await s3Rpc(() =>
       this.client.presignObject({
@@ -669,6 +697,7 @@ export class S3 {
     return result;
   }
 
+  /** Creates a host-mediated object access URL. */
   async createObjectAccessURL(
     ref: ObjectRef,
     options?: ObjectAccessURLOptions,
@@ -704,6 +733,7 @@ export class S3 {
     return this.objectAccessClient;
   }
 
+  /** Alias for `createObjectAccessURL`. */
   async createObjectAccessUrl(
     ref: ObjectRef,
     options?: ObjectAccessURLOptions,
@@ -711,6 +741,7 @@ export class S3 {
     return await this.createObjectAccessURL(ref, options);
   }
 
+  /** Alias for `createObjectAccessURL`. */
   async createAccessURL(
     ref: ObjectRef,
     options?: ObjectAccessURLOptions,
@@ -718,6 +749,7 @@ export class S3 {
     return await this.createObjectAccessURL(ref, options);
   }
 
+  /** Alias for `createObjectAccessURL`. */
   async createAccessUrl(
     ref: ObjectRef,
     options?: ObjectAccessURLOptions,
@@ -846,7 +878,10 @@ export class S3Object {
     return await this.client.createObjectAccessURL(this.ref, options);
   }
 
-  async createAccessUrl(options?: ObjectAccessURLOptions): Promise<ObjectAccessURL> {
+  /** Alias for `createAccessURL`. */
+  async createAccessUrl(
+    options?: ObjectAccessURLOptions,
+  ): Promise<ObjectAccessURL> {
     return await this.createAccessURL(options);
   }
 }

package/src/test-agent-contract.ts

@@ -0,0 +1,43 @@
+import { create } from "@bufbuild/protobuf";
+
+import {
+  AgentHost as AgentHostService,
+  AgentProvider as AgentProviderService,
+  CancelAgentProviderTurnRequestSchema,
+  CreateAgentProviderSessionRequestSchema,
+  CreateAgentProviderTurnRequestSchema,
+  ExecuteAgentToolResponseSchema,
+  GetAgentProviderCapabilitiesRequestSchema,
+  GetAgentProviderSessionRequestSchema,
+  GetAgentProviderTurnRequestSchema,
+  ListAgentProviderTurnEventsRequestSchema,
+  ListAgentToolsResponseSchema,
+  ListedAgentToolSchema,
+} from "./internal/gen/v1/agent_pb.ts";
+
+export const agentContractServices: Record<string, unknown> = {
+  AgentHost: AgentHostService,
+  AgentHostService,
+  AgentProvider: AgentProviderService,
+  AgentProviderService,
+};
+
+export const agentContractSchemas: Record<string, unknown> = {
+  CancelAgentProviderTurnRequestSchema,
+  CreateAgentProviderSessionRequestSchema,
+  CreateAgentProviderTurnRequestSchema,
+  ExecuteAgentToolResponseSchema,
+  GetAgentProviderCapabilitiesRequestSchema,
+  GetAgentProviderSessionRequestSchema,
+  GetAgentProviderTurnRequestSchema,
+  ListAgentProviderTurnEventsRequestSchema,
+  ListAgentToolsResponseSchema,
+  ListedAgentToolSchema,
+};
+
+export function createAgentContractMessage<T = unknown>(
+  schema: unknown,
+  input: Record<string, unknown>,
+): T {
+  return create(schema as never, input as never) as T;
+}

package/src/workflow-manager.ts

@@ -24,57 +24,84 @@ import {
   type ManagedWorkflowSchedule,
   type ManagedWorkflowEventTrigger,
   type WorkflowEvent,
-} from "../gen/v1/workflow_pb.ts";
+} from "./internal/gen/v1/workflow_pb.ts";
 import type { Request } from "./api.ts";
 
+/** Environment variable containing the workflow-manager host-service target. */
 export const ENV_WORKFLOW_MANAGER_SOCKET = "GESTALT_WORKFLOW_MANAGER_SOCKET";
-export const ENV_WORKFLOW_MANAGER_SOCKET_TOKEN = `${ENV_WORKFLOW_MANAGER_SOCKET}_TOKEN`;
+/** Environment variable containing the optional workflow-manager relay token. */
+export const ENV_WORKFLOW_MANAGER_SOCKET_TOKEN =
+  `${ENV_WORKFLOW_MANAGER_SOCKET}_TOKEN`;
 const WORKFLOW_MANAGER_RELAY_TOKEN_HEADER =
   "x-gestalt-host-service-relay-token";
 
+/** Managed workflow schedule message returned by the host manager. */
 export type ManagedWorkflowScheduleMessage = ManagedWorkflowSchedule;
+/** Managed workflow event-trigger message returned by the host manager. */
 export type ManagedWorkflowEventTriggerMessage = ManagedWorkflowEventTrigger;
+/** Workflow event message returned after publishing an event. */
 export type WorkflowEventMessage = WorkflowEvent;
+/** Shape accepted when creating a workflow schedule. */
 export type WorkflowManagerCreateScheduleInput = MessageInitShape<
   typeof WorkflowManagerCreateScheduleRequestSchema
 >;
+/** Shape accepted when creating an event trigger. */
 export type WorkflowManagerCreateTriggerInput = MessageInitShape<
   typeof WorkflowManagerCreateEventTriggerRequestSchema
 >;
+/** Shape accepted when fetching a workflow schedule. */
 export type WorkflowManagerGetScheduleInput = MessageInitShape<
   typeof WorkflowManagerGetScheduleRequestSchema
 >;
+/** Shape accepted when fetching an event trigger. */
 export type WorkflowManagerGetTriggerInput = MessageInitShape<
   typeof WorkflowManagerGetEventTriggerRequestSchema
 >;
+/** Shape accepted when updating a workflow schedule. */
 export type WorkflowManagerUpdateScheduleInput = MessageInitShape<
   typeof WorkflowManagerUpdateScheduleRequestSchema
 >;
+/** Shape accepted when updating an event trigger. */
 export type WorkflowManagerUpdateTriggerInput = MessageInitShape<
   typeof WorkflowManagerUpdateEventTriggerRequestSchema
 >;
+/** Shape accepted when deleting a workflow schedule. */
 export type WorkflowManagerDeleteScheduleInput = MessageInitShape<
   typeof WorkflowManagerDeleteScheduleRequestSchema
 >;
+/** Shape accepted when deleting an event trigger. */
 export type WorkflowManagerDeleteTriggerInput = MessageInitShape<
   typeof WorkflowManagerDeleteEventTriggerRequestSchema
 >;
+/** Shape accepted when pausing a workflow schedule. */
 export type WorkflowManagerPauseScheduleInput = MessageInitShape<
   typeof WorkflowManagerPauseScheduleRequestSchema
 >;
+/** Shape accepted when pausing an event trigger. */
 export type WorkflowManagerPauseTriggerInput = MessageInitShape<
   typeof WorkflowManagerPauseEventTriggerRequestSchema
 >;
+/** Shape accepted when resuming a workflow schedule. */
 export type WorkflowManagerResumeScheduleInput = MessageInitShape<
   typeof WorkflowManagerResumeScheduleRequestSchema
 >;
+/** Shape accepted when resuming an event trigger. */
 export type WorkflowManagerResumeTriggerInput = MessageInitShape<
   typeof WorkflowManagerResumeEventTriggerRequestSchema
 >;
+/** Shape accepted when publishing a workflow event. */
 export type WorkflowManagerPublishEventInput = MessageInitShape<
   typeof WorkflowManagerPublishEventRequestSchema
 >;
 
+/**
+ * Client for creating and controlling workflow schedules and event triggers.
+ *
+ * The constructor accepts either a Gestalt request or an invocation token. Each
+ * manager call forwards that token to the host service. When constructed from a
+ * request, create operations reuse the request idempotency key unless the call
+ * provides one explicitly.
+ */
 export class WorkflowManager {
   private readonly client: Client<typeof WorkflowManagerHostService>;
   private readonly invocationToken: string;
@@ -104,6 +131,7 @@ export class WorkflowManager {
     this.client = createClient(WorkflowManagerHostService, transport);
   }
 
+  /** Creates a workflow schedule. */
   async createSchedule(
     request: WorkflowManagerCreateScheduleInput,
   ): Promise<ManagedWorkflowScheduleMessage> {
@@ -114,6 +142,7 @@ export class WorkflowManager {
     });
   }
 
+  /** Fetches one workflow schedule. */
   async getSchedule(
     request: WorkflowManagerGetScheduleInput,
   ): Promise<ManagedWorkflowScheduleMessage> {
@@ -123,6 +152,7 @@ export class WorkflowManager {
     });
   }
 
+  /** Updates a workflow schedule. */
   async updateSchedule(
     request: WorkflowManagerUpdateScheduleInput,
   ): Promise<ManagedWorkflowScheduleMessage> {
@@ -132,6 +162,7 @@ export class WorkflowManager {
     });
   }
 
+  /** Deletes a workflow schedule. */
   async deleteSchedule(
     request: WorkflowManagerDeleteScheduleInput,
   ): Promise<void> {
@@ -141,6 +172,7 @@ export class WorkflowManager {
     });
   }
 
+  /** Pauses a workflow schedule. */
   async pauseSchedule(
     request: WorkflowManagerPauseScheduleInput,
   ): Promise<ManagedWorkflowScheduleMessage> {
@@ -150,6 +182,7 @@ export class WorkflowManager {
     });
   }
 
+  /** Resumes a workflow schedule. */
   async resumeSchedule(
     request: WorkflowManagerResumeScheduleInput,
   ): Promise<ManagedWorkflowScheduleMessage> {
@@ -159,6 +192,7 @@ export class WorkflowManager {
     });
   }
 
+  /** Creates an event trigger. */
   async createTrigger(
     request: WorkflowManagerCreateTriggerInput,
   ): Promise<ManagedWorkflowEventTriggerMessage> {
@@ -169,6 +203,7 @@ export class WorkflowManager {
     });
   }
 
+  /** Fetches one event trigger. */
   async getTrigger(
     request: WorkflowManagerGetTriggerInput,
   ): Promise<ManagedWorkflowEventTriggerMessage> {
@@ -178,6 +213,7 @@ export class WorkflowManager {
     });
   }
 
+  /** Updates an event trigger. */
   async updateTrigger(
     request: WorkflowManagerUpdateTriggerInput,
   ): Promise<ManagedWorkflowEventTriggerMessage> {
@@ -187,6 +223,7 @@ export class WorkflowManager {
     });
   }
 
+  /** Deletes an event trigger. */
   async deleteTrigger(
     request: WorkflowManagerDeleteTriggerInput,
   ): Promise<void> {
@@ -196,6 +233,7 @@ export class WorkflowManager {
     });
   }
 
+  /** Pauses an event trigger. */
   async pauseTrigger(
     request: WorkflowManagerPauseTriggerInput,
   ): Promise<ManagedWorkflowEventTriggerMessage> {
@@ -205,6 +243,7 @@ export class WorkflowManager {
     });
   }
 
+  /** Resumes an event trigger. */
   async resumeTrigger(
     request: WorkflowManagerResumeTriggerInput,
   ): Promise<ManagedWorkflowEventTriggerMessage> {
@@ -214,6 +253,7 @@ export class WorkflowManager {
     });
   }
 
+  /** Publishes an event into the workflow manager. */
   async publishEvent(
     request: WorkflowManagerPublishEventInput,
   ): Promise<WorkflowEventMessage> {

package/src/workflow.ts

@@ -44,12 +44,19 @@ import {
   type UpsertWorkflowProviderScheduleRequest,
   type WorkflowEvent,
   WorkflowRunStatus,
-} from "../gen/v1/workflow_pb.ts";
+} from "./internal/gen/v1/workflow_pb.ts";
 import { errorMessage, type MaybePromise } from "./api.ts";
 import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
 
+/** Environment variable containing the workflow-host service socket path. */
 export const ENV_WORKFLOW_HOST_SOCKET = "GESTALT_WORKFLOW_HOST_SOCKET";
 
+/**
+ * Generated workflow protocol message types commonly used by providers.
+ *
+ * These are re-exported so workflow provider code can type runs, schedules,
+ * triggers, and operation-invocation requests without importing from `gen`.
+ */
 export type {
   BoundWorkflowEventTrigger,
   BoundWorkflowRun,
@@ -77,6 +84,7 @@ export type {
 };
 export { WorkflowRunStatus };
 
+/** Handlers and runtime metadata for a workflow provider. */
 export interface WorkflowProviderOptions extends RuntimeProviderOptions {
   startRun: (
     request: StartWorkflowProviderRunRequest,
@@ -131,6 +139,7 @@ export interface WorkflowProviderOptions extends RuntimeProviderOptions {
   ) => MaybePromise<void>;
 }
 
+/** Runtime provider implementation for the Gestalt workflow host contract. */
 export class WorkflowProvider extends RuntimeProvider {
   readonly kind = "workflow" as const;
 
@@ -276,12 +285,14 @@ export class WorkflowProvider extends RuntimeProvider {
   }
 }
 
+/** Creates a workflow provider for export from a provider module. */
 export function defineWorkflowProvider(
   options: WorkflowProviderOptions,
 ): WorkflowProvider {
   return new WorkflowProvider(options);
 }
 
+/** Runtime type guard for workflow providers loaded from user modules. */
 export function isWorkflowProvider(value: unknown): value is WorkflowProvider {
   return (
     value instanceof WorkflowProvider ||
@@ -309,6 +320,7 @@ export function isWorkflowProvider(value: unknown): value is WorkflowProvider {
   );
 }
 
+/** Client for invoking operations from workflow provider code. */
 export class WorkflowHost {
   private readonly client: Client<typeof WorkflowHostService>;
 
@@ -326,6 +338,7 @@ export class WorkflowHost {
     this.client = createClient(WorkflowHostService, transport);
   }
 
+  /** Invokes an operation through the workflow host service. */
   async invokeOperation(
     request: InvokeWorkflowOperationRequest,
   ): Promise<InvokeWorkflowOperationResponse> {
@@ -333,6 +346,7 @@ export class WorkflowHost {
   }
 }
 
+/** Builds the Connect service implementation used by the TypeScript runtime. */
 export function createWorkflowProviderService(
   provider: WorkflowProvider,
 ): Partial<ServiceImpl<typeof WorkflowProviderService>> {

package/tsconfig.json

@@ -18,6 +18,6 @@
     "docs/entrypoints/**/*.ts",
     "src/**/*.ts",
     "tests/**/*.ts",
-    "gen/**/*.ts"
+    "src/internal/gen/**/*.ts"
   ]
 }