@valon-technologies/gestalt 0.0.1-alpha.11 → 0.0.1-alpha.13

package/src/plugin.ts

@@ -23,8 +23,20 @@ import {
   type Request,
   responseBrand,
   type Response,
+  type Subject,
 } from "./api.ts";
-import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
+import {
+  cloneHTTPSubjectRequest,
+  cloneHTTPSubjectResolutionContext,
+  type HTTPSubjectRequest,
+  type HTTPSubjectResolutionContext,
+  type HTTPSubjectResolver,
+} from "./http-subject.ts";
+import {
+  isRuntimeProvider,
+  RuntimeProvider,
+  type RuntimeProviderOptions,
+} from "./provider.ts";
 import type { Schema } from "./schema.ts";
 
 /**
@@ -84,6 +96,34 @@ export type SessionCatalogHandler = (
   request: Request,
 ) => MaybePromise<SessionCatalog | null | undefined>;
 
+/**
+ * Host-managed connection payload passed into a provider post-connect hook.
+ */
+export interface ConnectedToken {
+  id: string;
+  subjectId: string;
+  integration: string;
+  connection: string;
+  instance: string;
+  accessToken: string;
+  refreshToken: string;
+  scopes: string;
+  expiresAt?: Date | undefined;
+  lastRefreshedAt?: Date | undefined;
+  refreshErrorCount: number;
+  metadataJson: string;
+  metadata: Record<string, string>;
+  createdAt?: Date | undefined;
+  updatedAt?: Date | undefined;
+}
+
+/**
+ * Callback used to add derived metadata after a connection is established.
+ */
+export type PostConnectHandler = (
+  token: ConnectedToken,
+) => MaybePromise<Record<string, string> | null | undefined>;
+
 /**
  * Runtime hooks required to implement a plugin provider.
  */
@@ -93,6 +133,8 @@ export interface PluginDefinitionOptions extends RuntimeProviderOptions {
   connectionParams?: Record<string, ConnectionParamDefinition>;
   securitySchemes?: Record<string, HTTPSecurityScheme>;
   http?: Record<string, HTTPBinding>;
+  resolveHTTPSubject?: HTTPSubjectResolver;
+  postConnect?: PostConnectHandler;
   iconSvg?: string;
   operations: Array<OperationDefinition<any, any>>;
   sessionCatalog?: SessionCatalogHandler;
@@ -149,6 +191,8 @@ export class PluginProvider extends RuntimeProvider {
   readonly http: Record<string, HTTPBinding>;
 
   private readonly sessionCatalogHandler: SessionCatalogHandler | undefined;
+  private readonly httpSubjectResolver: HTTPSubjectResolver | undefined;
+  private readonly postConnectHandler: PostConnectHandler | undefined;
   private readonly operations = new Map<string, OperationDefinition<any, any>>();
 
   constructor(options: PluginDefinitionOptions) {
@@ -159,6 +203,8 @@ export class PluginProvider extends RuntimeProvider {
     this.connectionParams = normalizeConnectionParams(options.connectionParams);
     this.securitySchemes = normalizeHTTPSecuritySchemes(options.securitySchemes);
     this.http = normalizeHTTPBindings(options.http);
+    this.httpSubjectResolver = options.resolveHTTPSubject;
+    this.postConnectHandler = options.postConnect;
     this.sessionCatalogHandler = options.sessionCatalog;
 
     for (const rawEntry of options.operations) {
@@ -189,6 +235,36 @@ export class PluginProvider extends RuntimeProvider {
     return await this.sessionCatalogHandler?.(request);
   }
 
+  /**
+   * Reports whether the provider exposes a connect-time metadata hook.
+   */
+  supportsPostConnect(): boolean {
+    return this.postConnectHandler !== undefined;
+  }
+
+  /**
+   * Computes additional connection metadata after a successful connect flow.
+   */
+  async postConnectMetadata(
+    token: ConnectedToken,
+  ): Promise<Record<string, string> | null | undefined> {
+    return await this.postConnectHandler?.(cloneConnectedToken(token));
+  }
+
+  /**
+   * Resolves the concrete Gestalt subject for a verified hosted HTTP request,
+   * if the plugin opts into subject resolution.
+   */
+  async resolveHTTPSubject(
+    request: HTTPSubjectRequest,
+    context: HTTPSubjectResolutionContext,
+  ): Promise<Subject | null | undefined> {
+    return await this.httpSubjectResolver?.(
+      cloneHTTPSubjectRequest(request),
+      cloneHTTPSubjectResolutionContext(context),
+    );
+  }
+
   /**
    * Returns the static catalog emitted during provider startup.
    */
@@ -361,12 +437,27 @@ export function isPluginProvider(
 ): value is PluginProvider {
   return (
     value instanceof PluginProvider ||
-    (typeof value === "object" &&
-      value !== null &&
+    (isRuntimeProvider(value) &&
       "kind" in value &&
       (value as { kind?: unknown }).kind === "integration" &&
       "staticCatalog" in value &&
-      "execute" in value)
+      typeof (value as { staticCatalog?: unknown }).staticCatalog === "function" &&
+      "execute" in value &&
+      typeof (value as { execute?: unknown }).execute === "function" &&
+      "supportsSessionCatalog" in value &&
+      typeof (value as { supportsSessionCatalog?: unknown }).supportsSessionCatalog === "function" &&
+      "catalogForRequest" in value &&
+      typeof (value as { catalogForRequest?: unknown }).catalogForRequest === "function" &&
+      "supportsManifestMetadata" in value &&
+      typeof (value as { supportsManifestMetadata?: unknown }).supportsManifestMetadata === "function" &&
+      "writeManifestMetadata" in value &&
+      typeof (value as { writeManifestMetadata?: unknown }).writeManifestMetadata === "function" &&
+      "supportsPostConnect" in value &&
+      typeof (value as { supportsPostConnect?: unknown }).supportsPostConnect === "function" &&
+      "postConnectMetadata" in value &&
+      typeof (value as { postConnectMetadata?: unknown }).postConnectMetadata === "function" &&
+      "resolveHTTPSubject" in value &&
+      typeof (value as { resolveHTTPSubject?: unknown }).resolveHTTPSubject === "function")
   );
 }
 
@@ -396,6 +487,21 @@ function normalizeConnectionParams(
   return output;
 }
 
+function cloneConnectedToken(token: ConnectedToken): ConnectedToken {
+  return {
+    ...token,
+    metadata: {
+      ...(token.metadata ?? {}),
+    },
+    expiresAt: token.expiresAt ? new Date(token.expiresAt) : undefined,
+    lastRefreshedAt: token.lastRefreshedAt
+      ? new Date(token.lastRefreshedAt)
+      : undefined,
+    createdAt: token.createdAt ? new Date(token.createdAt) : undefined,
+    updatedAt: token.updatedAt ? new Date(token.updatedAt) : undefined,
+  };
+}
+
 function normalizeHTTPSecuritySchemes(
   input: Record<string, HTTPSecurityScheme> | undefined,
 ): Record<string, HTTPSecurityScheme> {
@@ -424,6 +530,21 @@ function cloneHTTPSecurityScheme(value: HTTPSecurityScheme): HTTPSecurityScheme
   if (value.description !== undefined) {
     output.description = value.description;
   }
+  if (value.signatureHeader !== undefined) {
+    output.signatureHeader = value.signatureHeader;
+  }
+  if (value.signaturePrefix !== undefined) {
+    output.signaturePrefix = value.signaturePrefix;
+  }
+  if (value.payloadTemplate !== undefined) {
+    output.payloadTemplate = value.payloadTemplate;
+  }
+  if (value.timestampHeader !== undefined) {
+    output.timestampHeader = value.timestampHeader;
+  }
+  if (value.maxAgeSeconds !== undefined) {
+    output.maxAgeSeconds = value.maxAgeSeconds;
+  }
   if (value.name !== undefined) {
     output.name = value.name;
   }

package/src/provider-kind.ts

@@ -44,6 +44,12 @@ const PROVIDER_KIND_DEFINITIONS = {
     defaultExportNames: ["workflow", "provider"],
     label: "workflow provider",
   },
+  agent: {
+    tokens: ["agent"],
+    formatToken: "agent",
+    defaultExportNames: ["agent", "provider"],
+    label: "agent provider",
+  },
   telemetry: {
     tokens: ["telemetry"],
     formatToken: "telemetry",

package/src/provider.ts

@@ -10,6 +10,7 @@ export type ProviderKind =
   | "secrets"
   | "s3"
   | "workflow"
+  | "agent"
   | "telemetry";
 
 /**
@@ -151,7 +152,17 @@ export function isRuntimeProvider(value: unknown): value is RuntimeProvider {
       value !== null &&
       "kind" in value &&
       "resolveName" in value &&
-      "configureProvider" in value)
+      typeof (value as { resolveName?: unknown }).resolveName === "function" &&
+      "configureProvider" in value &&
+      typeof (value as { configureProvider?: unknown }).configureProvider === "function" &&
+      "supportsHealthCheck" in value &&
+      typeof (value as { supportsHealthCheck?: unknown }).supportsHealthCheck === "function" &&
+      "healthCheck" in value &&
+      typeof (value as { healthCheck?: unknown }).healthCheck === "function" &&
+      "warnings" in value &&
+      typeof (value as { warnings?: unknown }).warnings === "function" &&
+      "closeProvider" in value &&
+      typeof (value as { closeProvider?: unknown }).closeProvider === "function")
   );
 }
 

package/src/runtime.ts

@@ -12,6 +12,9 @@ import {
 } from "@connectrpc/connect";
 import { connectNodeAdapter } from "@connectrpc/connect-node";
 
+import {
+  AgentProvider as AgentProviderService,
+} from "../gen/v1/agent_pb.ts";
 import {
   AuthenticationProvider as AuthenticationProviderService,
   AuthSessionSettingsSchema,
@@ -40,9 +43,14 @@ import {
   CatalogSchema as ProtoCatalogSchema,
   ConnectionMode as ProviderConnectionMode,
   GetSessionCatalogResponseSchema,
+  PostConnectResponseSchema,
+  ResolveHTTPSubjectResponseSchema,
   OperationResultSchema,
   ProviderMetadataSchema,
+  type HTTPSubjectRequest as ProtoHTTPSubjectRequest,
+  type IntegrationToken as ProtoIntegrationToken,
   type RequestContext as ProtoRequestContext,
+  type ResolveHTTPSubjectRequest as ProtoResolveHTTPSubjectRequest,
   IntegrationProvider as IntegrationProviderService,
   StartProviderResponseSchema,
   type ExecuteRequest,
@@ -60,6 +68,11 @@ import {
 import { S3 as S3Service } from "../gen/v1/s3_pb.ts";
 import { WorkflowProvider as WorkflowProviderService } from "../gen/v1/workflow_pb.ts";
 import { errorMessage, type Request } from "./api.ts";
+import {
+  AgentProvider,
+  createAgentProviderService,
+  isAgentProvider,
+} from "./agent.ts";
 import {
   AuthenticationProvider,
   isAuthenticationProvider,
@@ -69,6 +82,12 @@ import { CacheProvider, isCacheProvider } from "./cache.ts";
 import { SecretsProvider, isSecretsProvider } from "./secrets.ts";
 import { catalogToYaml, type Catalog } from "./catalog.ts";
 import {
+  HTTPSubjectResolutionError,
+  type HTTPSubjectRequest,
+  type HTTPSubjectResolutionContext,
+} from "./http-subject.ts";
+import {
+  type ConnectedToken,
   PluginProvider,
   connectionModeToProtoValue,
   connectionParamToProto,
@@ -119,6 +138,7 @@ export const CURRENT_PROTOCOL_VERSION = 3;
  * Command-line usage for the runtime entrypoint.
  */
 export const USAGE = "usage: bun run runtime.ts ROOT PROVIDER_TARGET";
+export { createAgentProviderService } from "./agent.ts";
 export { createWorkflowProviderService } from "./workflow.ts";
 
 /**
@@ -138,6 +158,7 @@ export type LoadedProvider =
   | CacheProvider
   | SecretsProvider
   | S3Provider
+  | AgentProvider
   | WorkflowProvider;
 
 type ProviderRuntimeEntry = {
@@ -197,6 +218,16 @@ const PROVIDER_RUNTIME_ENTRIES: Partial<
       router.service(S3Service, createS3Service(provider as S3Provider));
     },
   },
+  agent: {
+    isProvider: isAgentProvider as (value: unknown) => value is LoadedProvider,
+    protoKind: ProtoProviderKind.AGENT,
+    registerService(router, provider) {
+      router.service(
+        AgentProviderService,
+        createAgentProviderService(provider as AgentProvider),
+      );
+    },
+  },
   workflow: {
     isProvider: isWorkflowProvider as (value: unknown) => value is LoadedProvider,
     protoKind: ProtoProviderKind.WORKFLOW,
@@ -404,16 +435,20 @@ export function createRuntimeService(
 ): Partial<ServiceImpl<typeof ProviderLifecycle>> {
   return {
     async getProviderIdentity() {
-      return create(ProviderIdentitySchema, {
-        kind: providerRuntimeEntry(provider.kind).protoKind,
-        name: provider.name,
-        displayName: provider.displayName,
-        description: provider.description,
-        version: provider.version,
-        warnings: await provider.warnings(),
-        minProtocolVersion: CURRENT_PROTOCOL_VERSION,
-        maxProtocolVersion: CURRENT_PROTOCOL_VERSION,
-      });
+      try {
+        return create(ProviderIdentitySchema, {
+          kind: providerRuntimeEntry(provider.kind).protoKind,
+          name: provider.name,
+          displayName: provider.displayName,
+          description: provider.description,
+          version: provider.version,
+          warnings: await provider.warnings(),
+          minProtocolVersion: CURRENT_PROTOCOL_VERSION,
+          maxProtocolVersion: CURRENT_PROTOCOL_VERSION,
+        });
+      } catch (error) {
+        throw providerRuntimeError("provider identity", error);
+      }
     },
     async configureProvider(request: ConfigureProviderRequest) {
       assertProtocolVersion(request.protocolVersion);
@@ -423,10 +458,7 @@ export function createRuntimeService(
           objectFromUnknown(request.config),
         );
       } catch (error) {
-        throw new ConnectError(
-          `configure provider: ${errorMessage(error)}`,
-          Code.Unknown,
-        );
+        throw providerRuntimeError("configure provider", error);
       }
       return create(ConfigureProviderResponseSchema, {
         protocolVersion: CURRENT_PROTOCOL_VERSION,
@@ -465,27 +497,31 @@ export function createProviderService(
     throw new Error("provider is not a plugin provider");
   }
   return {
-    getMetadata() {
-      return create(ProviderMetadataSchema, {
-        name: provider.name,
-        displayName: provider.displayName,
-        description: provider.description,
-        connectionMode: connectionModeToProtoValue(
-          provider.connectionMode,
-        ) as ProviderConnectionMode,
-        authTypes: [...provider.authTypes],
-        connectionParams: Object.fromEntries(
-          Object.entries(provider.connectionParams).map(([key, value]) => [
-            key,
-            connectionParamToProto(value),
-          ]),
-        ),
-        staticCatalog: catalogToProto(provider.staticCatalog()),
-        supportsSessionCatalog: provider.supportsSessionCatalog(),
-        supportsPostConnect: false,
-        minProtocolVersion: CURRENT_PROTOCOL_VERSION,
-        maxProtocolVersion: CURRENT_PROTOCOL_VERSION,
-      });
+    async getMetadata() {
+      try {
+        return create(ProviderMetadataSchema, {
+          name: provider.name,
+          displayName: provider.displayName,
+          description: provider.description,
+          connectionMode: connectionModeToProtoValue(
+            provider.connectionMode,
+          ) as ProviderConnectionMode,
+          authTypes: [...provider.authTypes],
+          connectionParams: Object.fromEntries(
+            Object.entries(provider.connectionParams).map(([key, value]) => [
+              key,
+              connectionParamToProto(value),
+            ]),
+          ),
+          staticCatalog: catalogToProto(provider.staticCatalog()),
+          supportsSessionCatalog: provider.supportsSessionCatalog(),
+          supportsPostConnect: provider.supportsPostConnect(),
+          minProtocolVersion: CURRENT_PROTOCOL_VERSION,
+          maxProtocolVersion: CURRENT_PROTOCOL_VERSION,
+        });
+      } catch (error) {
+        throw providerRuntimeError("provider metadata", error);
+      }
     },
     async startProvider(request: StartProviderRequest) {
       assertProtocolVersion(request.protocolVersion);
@@ -495,10 +531,7 @@ export function createProviderService(
           objectFromUnknown(request.config),
         );
       } catch (error) {
-        throw new ConnectError(
-          `configure provider: ${errorMessage(error)}`,
-          Code.Unknown,
-        );
+        throw providerRuntimeError("configure provider", error);
       }
       return create(StartProviderResponseSchema, {
         protocolVersion: CURRENT_PROTOCOL_VERSION,
@@ -519,6 +552,36 @@ export function createProviderService(
         ),
       );
     },
+    async resolveHTTPSubject(request: ProtoResolveHTTPSubjectRequest) {
+      let subject;
+      try {
+        subject = await provider.resolveHTTPSubject(
+          providerHTTPSubjectRequest(request.request),
+          providerHTTPSubjectResolutionContext(request.context),
+        );
+      } catch (error) {
+        if (error instanceof HTTPSubjectResolutionError) {
+          return create(ResolveHTTPSubjectResponseSchema, {
+            rejectStatus: error.status,
+            rejectMessage: error.message,
+          });
+        }
+        throw new ConnectError(
+          `resolve http subject: ${errorMessage(error)}`,
+          Code.Unknown,
+        );
+      }
+      return create(ResolveHTTPSubjectResponseSchema, subject
+        ? {
+            subject: {
+              id: subject.id,
+              kind: subject.kind,
+              displayName: subject.displayName,
+              authSource: subject.authSource,
+            },
+          }
+        : {});
+    },
     async getSessionCatalog(request: GetSessionCatalogRequest) {
       let catalog: Catalog | Record<string, unknown> | null | undefined;
       try {
@@ -545,11 +608,29 @@ export function createProviderService(
         catalog: catalogToProto(catalog),
       });
     },
-    async postConnect() {
-      throw new ConnectError(
-        "provider does not support post connect",
-        Code.Unimplemented,
-      );
+    async postConnect(request) {
+      if (!provider.supportsPostConnect()) {
+        throw new ConnectError(
+          "provider does not support post connect",
+          Code.Unimplemented,
+        );
+      }
+      let metadata: Record<string, string> | null | undefined;
+      try {
+        metadata = await provider.postConnectMetadata(
+          providerConnectedToken(request.token),
+        );
+      } catch (error) {
+        throw new ConnectError(
+          `post connect: ${errorMessage(error)}`,
+          Code.Unknown,
+        );
+      }
+      return create(PostConnectResponseSchema, {
+        metadata: {
+          ...(metadata ?? {}),
+        },
+      });
     },
   };
 }
@@ -752,6 +833,71 @@ function providerRequest(
   };
 }
 
+function providerHTTPSubjectRequest(
+  request?: ProtoHTTPSubjectRequest,
+): HTTPSubjectRequest {
+  return {
+    binding: request?.binding ?? "",
+    method: request?.method ?? "",
+    path: request?.path ?? "",
+    contentType: request?.contentType ?? "",
+    headers: providerStringLists(request?.headers),
+    query: providerStringLists(request?.query),
+    params: objectFromUnknown(request?.params),
+    rawBody: new Uint8Array(request?.rawBody ?? new Uint8Array()),
+    securityScheme: request?.securityScheme ?? "",
+    verifiedSubject: request?.verifiedSubject ?? "",
+    verifiedClaims: {
+      ...(request?.verifiedClaims ?? {}),
+    },
+  };
+}
+
+function providerHTTPSubjectResolutionContext(
+  requestContext?: ProtoRequestContext,
+): HTTPSubjectResolutionContext {
+  const request = providerRequest("", {}, requestContext);
+  return {
+    subject: request.subject,
+    credential: request.credential,
+    access: request.access,
+    workflow: request.workflow,
+  };
+}
+
+function providerConnectedToken(
+  token?: ProtoIntegrationToken,
+): ConnectedToken {
+  const metadataJson = token?.metadataJson ?? "";
+  return {
+    id: token?.id ?? "",
+    subjectId: token?.userId ?? "",
+    integration: token?.integration ?? "",
+    connection: token?.connection ?? "",
+    instance: token?.instance ?? "",
+    accessToken: token?.accessToken ?? "",
+    refreshToken: token?.refreshToken ?? "",
+    scopes: token?.scopes ?? "",
+    expiresAt: timestampToDate(token?.expiresAt),
+    lastRefreshedAt: timestampToDate(token?.lastRefreshedAt),
+    refreshErrorCount: token?.refreshErrorCount ?? 0,
+    metadataJson,
+    metadata: stringRecordFromJSON(metadataJson),
+    createdAt: timestampToDate(token?.createdAt),
+    updatedAt: timestampToDate(token?.updatedAt),
+  };
+}
+
+function providerStringLists(
+  input: Record<string, { values?: string[] }> | undefined,
+): Record<string, string[]> {
+  const output: Record<string, string[]> = {};
+  for (const [key, value] of Object.entries(input ?? {})) {
+    output[key] = [...(value.values ?? [])];
+  }
+  return output;
+}
+
 function providerRuntimeEntry(
   kind: ProviderKind,
 ): ProviderRuntimeEntry {
@@ -764,6 +910,10 @@ function providerRuntimeEntry(
   return entry;
 }
 
+function providerRuntimeError(label: string, error: unknown): ConnectError {
+  return new ConnectError(`${label}: ${errorMessage(error)}`, Code.Unknown);
+}
+
 function resolveLoadedProvider(
   candidate: unknown,
   kind: ProviderKind,
@@ -850,6 +1000,45 @@ function normalizeBigInt(value: number | bigint): bigint {
   return BigInt(Math.max(0, Math.trunc(value)));
 }
 
+function timestampToDate(
+  value: { seconds: bigint; nanos: number } | undefined,
+): Date | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const seconds = Number(value.seconds ?? 0n);
+  const nanos = Number(value.nanos ?? 0);
+  if (!Number.isFinite(seconds) || !Number.isFinite(nanos)) {
+    return undefined;
+  }
+  const millis = (seconds * 1000) + Math.trunc(nanos / 1_000_000);
+  if (!Number.isFinite(millis)) {
+    return undefined;
+  }
+  return new Date(millis);
+}
+
+function stringRecordFromJSON(value: string): Record<string, string> {
+  if (!value.trim()) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return {};
+    }
+    const output: Record<string, string> = {};
+    for (const [key, entry] of Object.entries(parsed)) {
+      if (typeof entry === "string") {
+        output[key] = entry;
+      }
+    }
+    return output;
+  } catch {
+    return {};
+  }
+}
+
 function cloneUint8Array(value: Uint8Array | undefined): Uint8Array {
   if (!value) {
     return new Uint8Array();