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

package/src/index.ts

@@ -32,6 +32,7 @@ export {
   Authorization,
   AuthorizationClient,
   ENV_AUTHORIZATION_SOCKET,
+  ENV_AUTHORIZATION_SOCKET_TOKEN,
   type AuthorizationActionSearchMessage,
   type AuthorizationDecisionMessage,
   type AuthorizationEvaluateInput,
@@ -105,8 +106,25 @@ export {
   type PluginInvocationGrant,
   type PluginInvokeOptions,
 } from "./invoker.ts";
+export {
+  ENV_AGENT_MANAGER_SOCKET,
+  ENV_AGENT_MANAGER_SOCKET_TOKEN,
+  AgentManager,
+  type AgentManagerCancelTurnInput,
+  type AgentManagerCreateSessionInput,
+  type AgentManagerCreateTurnInput,
+  type AgentManagerGetSessionInput,
+  type AgentManagerGetTurnInput,
+  type AgentManagerListInteractionsInput,
+  type AgentManagerListSessionsInput,
+  type AgentManagerListTurnEventsInput,
+  type AgentManagerListTurnsInput,
+  type AgentManagerResolveInteractionInput,
+  type AgentManagerUpdateSessionInput,
+} from "./agent-manager.ts";
 export {
   ENV_WORKFLOW_MANAGER_SOCKET,
+  ENV_WORKFLOW_MANAGER_SOCKET_TOKEN,
   WorkflowManager,
   type ManagedWorkflowEventTriggerMessage,
   type ManagedWorkflowScheduleMessage,
@@ -155,6 +173,7 @@ export {
   type SecretsProviderOptions,
 } from "./secrets.ts";
 export {
+  type ConnectedToken,
   PluginProvider,
   connectionModeToProtoValue,
   connectionParamToProto,
@@ -165,6 +184,7 @@ export {
   type ConnectionParamDefinition,
   type OperationDefinition,
   type OperationOptions,
+  type PostConnectHandler,
   type PluginDefinitionOptions,
   type SessionCatalog,
   type SessionCatalogHandler,
@@ -255,7 +275,10 @@ export {
   createS3Service,
   defineS3Provider,
   isS3Provider,
+  ENV_S3_SOCKET,
+  ENV_S3_SOCKET_TOKEN,
   s3SocketEnv,
+  s3SocketTokenEnv,
   type ByteRange,
   type CopyOptions,
   type ListOptions,
@@ -271,6 +294,50 @@ export {
   type S3ProviderOptions,
   type WriteOptions,
 } from "./s3.ts";
+export {
+  ENV_AGENT_HOST_SOCKET,
+  AgentHost,
+  AgentExecutionStatus,
+  AgentInteractionState,
+  AgentInteractionType,
+  AgentMessagePartType,
+  AgentProvider,
+  AgentSessionState,
+  AgentToolSourceMode,
+  createAgentProviderService,
+  defineAgentProvider,
+  isAgentProvider,
+  type AgentActor,
+  type AgentInteraction,
+  type AgentMessage,
+  type AgentMessagePart,
+  type AgentMessagePartImageRef,
+  type AgentMessagePartToolCall,
+  type AgentMessagePartToolResult,
+  type AgentProviderCapabilities,
+  type AgentProviderOptions,
+  type AgentSession,
+  type AgentToolRef,
+  type AgentTurn,
+  type AgentTurnEvent,
+  type BoundAgentToolTarget,
+  type CancelAgentProviderTurnRequest,
+  type CreateAgentProviderSessionRequest,
+  type CreateAgentProviderTurnRequest,
+  type ExecuteAgentToolRequest,
+  type ExecuteAgentToolResponse,
+  type GetAgentProviderCapabilitiesRequest,
+  type GetAgentProviderInteractionRequest,
+  type GetAgentProviderSessionRequest,
+  type GetAgentProviderTurnRequest,
+  type ListAgentProviderInteractionsRequest,
+  type ListAgentProviderSessionsRequest,
+  type ListAgentProviderTurnEventsRequest,
+  type ListAgentProviderTurnsRequest,
+  type ResolvedAgentTool,
+  type ResolveAgentProviderInteractionRequest,
+  type UpdateAgentProviderSessionRequest,
+} from "./agent.ts";
 export {
   ENV_WORKFLOW_HOST_SOCKET,
   WorkflowHost,

package/src/manifest-metadata.ts

@@ -47,6 +47,7 @@ export interface HTTPAck {
 export interface HTTPBinding {
   path: string;
   method: string;
+  credentialMode?: "none" | "user";
   requestBody?: HTTPRequestBody;
   security: string;
   target: string;

package/src/plugin.ts

@@ -32,7 +32,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";
 
 /**
@@ -92,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.
  */
@@ -102,6 +134,7 @@ export interface PluginDefinitionOptions extends RuntimeProviderOptions {
   securitySchemes?: Record<string, HTTPSecurityScheme>;
   http?: Record<string, HTTPBinding>;
   resolveHTTPSubject?: HTTPSubjectResolver;
+  postConnect?: PostConnectHandler;
   iconSvg?: string;
   operations: Array<OperationDefinition<any, any>>;
   sessionCatalog?: SessionCatalogHandler;
@@ -159,6 +192,7 @@ export class PluginProvider extends RuntimeProvider {
 
   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) {
@@ -170,6 +204,7 @@ export class PluginProvider extends RuntimeProvider {
     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 +235,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.
@@ -386,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")
   );
 }
 
@@ -421,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> {

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,10 +43,12 @@ 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,
@@ -63,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,
@@ -77,6 +87,7 @@ import {
   type HTTPSubjectResolutionContext,
 } from "./http-subject.ts";
 import {
+  type ConnectedToken,
   PluginProvider,
   connectionModeToProtoValue,
   connectionParamToProto,
@@ -127,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";
 
 /**
@@ -146,6 +158,7 @@ export type LoadedProvider =
   | CacheProvider
   | SecretsProvider
   | S3Provider
+  | AgentProvider
   | WorkflowProvider;
 
 type ProviderRuntimeEntry = {
@@ -205,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,
@@ -412,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);
@@ -431,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,
@@ -473,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);
@@ -503,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,
@@ -583,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 ?? {}),
+        },
+      });
     },
   };
 }
@@ -822,6 +865,29 @@ function providerHTTPSubjectResolutionContext(
   };
 }
 
+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[]> {
@@ -844,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,
@@ -930,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();