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

package/src/plugin.ts

@@ -7,15 +7,6 @@ import {
   schemaToParameters,
   writeCatalogYaml,
 } from "./catalog.ts";
-import {
-  type HTTPAck,
-  type HTTPBinding,
-  type HTTPRequestBody,
-  type HTTPSecurityScheme,
-  type PluginManifestMetadata,
-  hasPluginManifestMetadata,
-  writeManifestMetadataYaml,
-} from "./manifest-metadata.ts";
 import {
   errorMessage,
   type MaybePromise,
@@ -32,7 +23,11 @@ import {
   type HTTPSubjectResolutionContext,
   type HTTPSubjectResolver,
 } from "./http-subject.ts";
-import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
+import {
+  isRuntimeProvider,
+  RuntimeProvider,
+  type RuntimeProviderOptions,
+} from "./provider.ts";
 import type { Schema } from "./schema.ts";
 
 /**
@@ -42,7 +37,7 @@ export type ConnectionMode =
   | "unspecified"
   | "none"
   | "user"
-  | "identity";
+  | "platform";
 
 /**
  * Metadata for a single connection parameter exposed by a provider.
@@ -92,6 +87,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.
  */
@@ -99,9 +122,8 @@ export interface PluginDefinitionOptions extends RuntimeProviderOptions {
   connectionMode?: ConnectionMode;
   authTypes?: string[];
   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;
@@ -154,11 +176,10 @@ export class PluginProvider extends RuntimeProvider {
   readonly connectionMode: ConnectionMode;
   readonly authTypes: string[];
   readonly connectionParams: Record<string, ConnectionParamDefinition>;
-  readonly securitySchemes: Record<string, HTTPSecurityScheme>;
-  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) {
@@ -167,9 +188,8 @@ export class PluginProvider extends RuntimeProvider {
     this.connectionMode = options.connectionMode ?? "unspecified";
     this.authTypes = [...(options.authTypes ?? [])];
     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) {
@@ -200,6 +220,22 @@ 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.
@@ -295,38 +331,6 @@ export class PluginProvider extends RuntimeProvider {
     return catalogToJson(this.staticCatalog());
   }
 
-  /**
-   * Returns generated manifest-backed HTTP/security metadata for the provider.
-   */
-  staticManifestMetadata(): PluginManifestMetadata {
-    const metadata: PluginManifestMetadata = {};
-    if (Object.keys(this.securitySchemes).length > 0) {
-      metadata.securitySchemes = cloneHTTPSecuritySchemes(this.securitySchemes);
-    }
-    if (Object.keys(this.http).length > 0) {
-      metadata.http = cloneHTTPBindings(this.http);
-    }
-    return metadata;
-  }
-
-  /**
-   * Reports whether the provider emits manifest metadata in addition to catalog metadata.
-   */
-  supportsManifestMetadata(): boolean {
-    return hasPluginManifestMetadata(this.staticManifestMetadata());
-  }
-
-  /**
-   * Writes generated manifest metadata to disk as YAML.
-   */
-  writeManifestMetadata(path: string): void {
-    const metadata = this.staticManifestMetadata();
-    if (!hasPluginManifestMetadata(metadata)) {
-      return;
-    }
-    writeManifestMetadataYaml(path, metadata);
-  }
-
   /**
    * Executes an operation against validated input and request metadata.
    */
@@ -386,12 +390,23 @@ 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" &&
+      "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")
   );
 }
 
@@ -421,134 +436,19 @@ function normalizeConnectionParams(
   return output;
 }
 
-function normalizeHTTPSecuritySchemes(
-  input: Record<string, HTTPSecurityScheme> | undefined,
-): Record<string, HTTPSecurityScheme> {
-  const output: Record<string, HTTPSecurityScheme> = {};
-  for (const [key, value] of Object.entries(input ?? {})) {
-    output[key] = cloneHTTPSecurityScheme(value);
-  }
-  return output;
-}
-
-function cloneHTTPSecuritySchemes(
-  input: Record<string, HTTPSecurityScheme>,
-): Record<string, HTTPSecurityScheme> {
-  const output: Record<string, HTTPSecurityScheme> = {};
-  for (const [key, value] of Object.entries(input)) {
-    output[key] = cloneHTTPSecurityScheme(value);
-  }
-  return output;
-}
-
-function cloneHTTPSecurityScheme(value: HTTPSecurityScheme): HTTPSecurityScheme {
-  const output: HTTPSecurityScheme = {};
-  if (value.type !== undefined) {
-    output.type = value.type;
-  }
-  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;
-  }
-  if (value.in !== undefined) {
-    output.in = value.in;
-  }
-  if (value.scheme !== undefined) {
-    output.scheme = value.scheme;
-  }
-  if (value.secret) {
-    output.secret = {
-      ...value.secret,
-    };
-  }
-  return output;
-}
-
-function normalizeHTTPBindings(
-  input: Record<string, HTTPBinding> | undefined,
-): Record<string, HTTPBinding> {
-  const output: Record<string, HTTPBinding> = {};
-  for (const [key, value] of Object.entries(input ?? {})) {
-    output[key] = cloneHTTPBinding(value);
-  }
-  return output;
-}
-
-function cloneHTTPBindings(
-  input: Record<string, HTTPBinding>,
-): Record<string, HTTPBinding> {
-  const output: Record<string, HTTPBinding> = {};
-  for (const [key, value] of Object.entries(input)) {
-    output[key] = cloneHTTPBinding(value);
-  }
-  return output;
-}
-
-function cloneHTTPBinding(value: HTTPBinding): HTTPBinding {
-  const output: HTTPBinding = {
-    path: value.path,
-    method: value.method,
-    security: value.security,
-    target: value.target,
+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,
   };
-  if (value.requestBody) {
-    output.requestBody = cloneHTTPRequestBody(value.requestBody);
-  }
-  if (value.ack) {
-    output.ack = cloneHTTPAck(value.ack);
-  }
-  return output;
-}
-
-function cloneHTTPRequestBody(value: HTTPRequestBody): HTTPRequestBody {
-  const output: HTTPRequestBody = {};
-  if (value.required !== undefined) {
-    output.required = value.required;
-  }
-  if (value.content) {
-    output.content = {};
-    for (const key of Object.keys(value.content)) {
-      output.content[key] = {};
-    }
-  }
-  return output;
-}
-
-function cloneHTTPAck(value: HTTPAck): HTTPAck {
-  const output: HTTPAck = {};
-  if (value.status !== undefined) {
-    output.status = value.status;
-  }
-  if (value.headers) {
-    output.headers = {
-      ...value.headers,
-    };
-  }
-  if (value.body !== undefined) {
-    output.body = cloneHTTPBodyValue(value.body);
-  }
-  return output;
-}
-
-function cloneHTTPBodyValue<T>(value: T): T {
-  return structuredClone(value);
 }
 
 function isResponse(value: unknown): value is Response<unknown> {
@@ -615,8 +515,8 @@ export function connectionModeToProtoValue(mode: ConnectionMode): number {
       return 1;
     case "user":
       return 2;
-    case "identity":
-      return 3;
+    case "platform":
+      return 5;
     case "unspecified":
     default:
       return 0;

package/src/pluginruntime.ts

@@ -0,0 +1,220 @@
+import { create, type MessageInitShape } from "@bufbuild/protobuf";
+import { EmptySchema } from "@bufbuild/protobuf/wkt";
+import {
+  Code,
+  ConnectError,
+  type ServiceImpl,
+} from "@connectrpc/connect";
+
+import {
+  HostedPluginSchema,
+  ListPluginRuntimeSessionsResponseSchema,
+  PluginRuntimeEgressMode,
+  PluginRuntimeHostServiceAccess,
+  PluginRuntimeHostServiceBindingSchema,
+  PluginRuntimeProvider as PluginRuntimeProviderService,
+  PluginRuntimeSessionSchema,
+  PluginRuntimeSupportSchema,
+  type BindPluginRuntimeHostServiceRequest,
+  type GetPluginRuntimeSessionRequest,
+  type HostedPlugin,
+  type ListPluginRuntimeSessionsRequest,
+  type PluginRuntimeHostServiceBinding,
+  type PluginRuntimeSession,
+  type PluginRuntimeSupport,
+  type StartHostedPluginRequest,
+  type StartPluginRuntimeSessionRequest,
+  type StopPluginRuntimeSessionRequest,
+} from "../gen/v1/pluginruntime_pb.ts";
+import { errorMessage, type MaybePromise } from "./api.ts";
+import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
+
+export type {
+  BindPluginRuntimeHostServiceRequest,
+  GetPluginRuntimeSessionRequest,
+  HostedPlugin,
+  ListPluginRuntimeSessionsRequest,
+  PluginRuntimeHostServiceBinding,
+  PluginRuntimeSession,
+  PluginRuntimeSupport,
+  StartHostedPluginRequest,
+  StartPluginRuntimeSessionRequest,
+  StopPluginRuntimeSessionRequest,
+};
+export { PluginRuntimeEgressMode, PluginRuntimeHostServiceAccess };
+
+export interface PluginRuntimeProviderOptions extends RuntimeProviderOptions {
+  getSupport: () => MaybePromise<MessageInitShape<typeof PluginRuntimeSupportSchema>>;
+  startSession: (
+    request: StartPluginRuntimeSessionRequest,
+  ) => MaybePromise<MessageInitShape<typeof PluginRuntimeSessionSchema>>;
+  getSession: (
+    request: GetPluginRuntimeSessionRequest,
+  ) => MaybePromise<MessageInitShape<typeof PluginRuntimeSessionSchema>>;
+  listSessions: (
+    request: ListPluginRuntimeSessionsRequest,
+  ) => MaybePromise<MessageInitShape<typeof PluginRuntimeSessionSchema>[]>;
+  stopSession: (request: StopPluginRuntimeSessionRequest) => MaybePromise<void>;
+  bindHostService: (
+    request: BindPluginRuntimeHostServiceRequest,
+  ) => MaybePromise<MessageInitShape<typeof PluginRuntimeHostServiceBindingSchema>>;
+  startPlugin: (
+    request: StartHostedPluginRequest,
+  ) => MaybePromise<MessageInitShape<typeof HostedPluginSchema>>;
+}
+
+export class PluginRuntimeProvider extends RuntimeProvider {
+  readonly kind = "runtime" as const;
+
+  private readonly getSupportHandler: PluginRuntimeProviderOptions["getSupport"];
+  private readonly startSessionHandler: PluginRuntimeProviderOptions["startSession"];
+  private readonly getSessionHandler: PluginRuntimeProviderOptions["getSession"];
+  private readonly listSessionsHandler: PluginRuntimeProviderOptions["listSessions"];
+  private readonly stopSessionHandler: PluginRuntimeProviderOptions["stopSession"];
+  private readonly bindHostServiceHandler: PluginRuntimeProviderOptions["bindHostService"];
+  private readonly startPluginHandler: PluginRuntimeProviderOptions["startPlugin"];
+
+  constructor(options: PluginRuntimeProviderOptions) {
+    super(options);
+    this.getSupportHandler = options.getSupport;
+    this.startSessionHandler = options.startSession;
+    this.getSessionHandler = options.getSession;
+    this.listSessionsHandler = options.listSessions;
+    this.stopSessionHandler = options.stopSession;
+    this.bindHostServiceHandler = options.bindHostService;
+    this.startPluginHandler = options.startPlugin;
+  }
+
+  async getSupport(): Promise<MessageInitShape<typeof PluginRuntimeSupportSchema>> {
+    return await this.getSupportHandler();
+  }
+
+  async startSession(
+    request: StartPluginRuntimeSessionRequest,
+  ): Promise<MessageInitShape<typeof PluginRuntimeSessionSchema>> {
+    return await this.startSessionHandler(request);
+  }
+
+  async getSession(
+    request: GetPluginRuntimeSessionRequest,
+  ): Promise<MessageInitShape<typeof PluginRuntimeSessionSchema>> {
+    return await this.getSessionHandler(request);
+  }
+
+  async listSessions(
+    request: ListPluginRuntimeSessionsRequest,
+  ): Promise<MessageInitShape<typeof PluginRuntimeSessionSchema>[]> {
+    return await this.listSessionsHandler(request);
+  }
+
+  async stopSession(request: StopPluginRuntimeSessionRequest): Promise<void> {
+    await this.stopSessionHandler(request);
+  }
+
+  async bindHostService(
+    request: BindPluginRuntimeHostServiceRequest,
+  ): Promise<MessageInitShape<typeof PluginRuntimeHostServiceBindingSchema>> {
+    return await this.bindHostServiceHandler(request);
+  }
+
+  async startPlugin(
+    request: StartHostedPluginRequest,
+  ): Promise<MessageInitShape<typeof HostedPluginSchema>> {
+    return await this.startPluginHandler(request);
+  }
+}
+
+export function definePluginRuntimeProvider(
+  options: PluginRuntimeProviderOptions,
+): PluginRuntimeProvider {
+  return new PluginRuntimeProvider(options);
+}
+
+export function isPluginRuntimeProvider(
+  value: unknown,
+): value is PluginRuntimeProvider {
+  return (
+    value instanceof PluginRuntimeProvider ||
+    (typeof value === "object" &&
+      value !== null &&
+      "kind" in value &&
+      (value as { kind?: unknown }).kind === "runtime" &&
+      "getSupport" in value &&
+      "startSession" in value &&
+      "startPlugin" in value)
+  );
+}
+
+export function createPluginRuntimeProviderService(
+  provider: PluginRuntimeProvider,
+): Partial<ServiceImpl<typeof PluginRuntimeProviderService>> {
+  return {
+    async getSupport() {
+      return create(
+        PluginRuntimeSupportSchema,
+        await invokePluginRuntimeProvider("get support", () =>
+          provider.getSupport(),
+        ),
+      );
+    },
+    async startSession(request) {
+      return create(
+        PluginRuntimeSessionSchema,
+        await invokePluginRuntimeProvider("start session", () =>
+          provider.startSession(request),
+        ),
+      );
+    },
+    async getSession(request) {
+      return create(
+        PluginRuntimeSessionSchema,
+        await invokePluginRuntimeProvider("get session", () =>
+          provider.getSession(request),
+        ),
+      );
+    },
+    async listSessions(request) {
+      return create(ListPluginRuntimeSessionsResponseSchema, {
+        sessions: await invokePluginRuntimeProvider("list sessions", () =>
+          provider.listSessions(request),
+        ),
+      });
+    },
+    async stopSession(request) {
+      await invokePluginRuntimeProvider("stop session", () =>
+        provider.stopSession(request),
+      );
+      return create(EmptySchema);
+    },
+    async bindHostService(request) {
+      return create(
+        PluginRuntimeHostServiceBindingSchema,
+        await invokePluginRuntimeProvider("bind host service", () =>
+          provider.bindHostService(request),
+        ),
+      );
+    },
+    async startPlugin(request) {
+      return create(
+        HostedPluginSchema,
+        await invokePluginRuntimeProvider("start plugin", () =>
+          provider.startPlugin(request),
+        ),
+      );
+    },
+  };
+}
+
+async function invokePluginRuntimeProvider<T>(
+  label: string,
+  fn: () => MaybePromise<T>,
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    throw new ConnectError(
+      `plugin runtime provider ${label}: ${errorMessage(error)}`,
+      Code.Unknown,
+    );
+  }
+}

package/src/provider-kind.ts

@@ -38,12 +38,24 @@ const PROVIDER_KIND_DEFINITIONS = {
     defaultExportNames: ["s3", "provider"],
     label: "s3 provider",
   },
+  runtime: {
+    tokens: ["runtime"],
+    formatToken: "runtime",
+    defaultExportNames: ["runtime", "provider"],
+    label: "runtime provider",
+  },
   workflow: {
     tokens: ["workflow"],
     formatToken: "workflow",
     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

@@ -9,7 +9,9 @@ export type ProviderKind =
   | "cache"
   | "secrets"
   | "s3"
+  | "runtime"
   | "workflow"
+  | "agent"
   | "telemetry";
 
 /**
@@ -41,6 +43,12 @@ export type HealthCheckHandler = () => MaybePromise<void>;
  */
 export type WarningsHandler = () => MaybePromise<string[]>;
 
+/**
+ * Optional hook invoked after configuration when the host is ready for
+ * provider-owned background work to begin.
+ */
+export type StartHandler = () => MaybePromise<void>;
+
 /**
  * Optional shutdown hook invoked when the provider process exits.
  */
@@ -57,6 +65,7 @@ export interface RuntimeProviderOptions {
   configure?: ConfigureHandler;
   healthCheck?: HealthCheckHandler;
   warnings?: string[] | WarningsHandler;
+  start?: StartHandler;
   close?: CloseHandler;
 }
 
@@ -74,6 +83,7 @@ export abstract class RuntimeProvider {
   private readonly configureHandler: ConfigureHandler | undefined;
   private readonly healthCheckHandler: HealthCheckHandler | undefined;
   private readonly warningsSource: string[] | WarningsHandler | undefined;
+  private readonly startHandler: StartHandler | undefined;
   private readonly closeHandler: CloseHandler | undefined;
 
   protected constructor(options: RuntimeProviderOptions) {
@@ -86,6 +96,7 @@ export abstract class RuntimeProvider {
     this.warningsSource = Array.isArray(options.warnings)
       ? [...options.warnings]
       : options.warnings;
+    this.startHandler = options.start;
     this.closeHandler = options.close;
   }
 
@@ -126,6 +137,10 @@ export abstract class RuntimeProvider {
     await this.healthCheckHandler?.();
   }
 
+  async startProvider(): Promise<void> {
+    await this.startHandler?.();
+  }
+
   async warnings(): Promise<string[]> {
     if (!this.warningsSource) {
       return [];
@@ -151,7 +166,19 @@ 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" &&
+      "startProvider" in value &&
+      typeof (value as { startProvider?: unknown }).startProvider === "function" &&
+      "warnings" in value &&
+      typeof (value as { warnings?: unknown }).warnings === "function" &&
+      "closeProvider" in value &&
+      typeof (value as { closeProvider?: unknown }).closeProvider === "function")
   );
 }